racket-wiki/HANDOFF.md

Overdracht racket-wiki

Bijgewerkt: 22 augustus 2026

Project in het kort

racket-wiki is een kleine, zelfgehoste wiki met:

• een Racket-backend op web-server-lib;
• PostgreSQL als opslag voor gebruikers, sessies, pagina's, versies, bijlagen en concept maps (CMaps);
• een frontend in gewone HTML, CSS en JavaScript, zonder npm- of bundlerstap;
• EasyMDE/Marked voor Markdown, DOMPurify voor sanitizing, highlight.js voor code en diff2html voor versieverschillen;
• lokale, tijdens setup gedownloade frontendbibliotheken, zodat normaal gebruik geen CDN nodig heeft.

De ontwikkelversie is 0.2.99 (info.rkt). De huidige PostgreSQL-schemaversie is 12 (private/migrations.rkt).

Belangrijk: huidige werkboom

De branch is main en volgt origin/main. De laatste commit is:

63b7ca0 cmap functions, email, architecture documentation.

Er staan belangrijke, nog niet gecommitte wijzigingen in de werkboom. Die vormen samen de ontwikkeling van 0.2.95 t/m 0.2.99 en moeten worden behouden. Bij de laatste inventarisatie waren gewijzigd:

README.md
architecture/pages/data-en-versies.md
architecture/pages/gedrag.md
architecture/pages/testbaarheid.md
info.rkt
private/cmap-storage.rkt
private/migrations.rkt
server.rkt
static/cmap/cmap-racket-wiki.js
static/cmap/cmap.css
static/cmap/cmap.js
static/css/wiki.css
static/index.html
static/js/wiki.js
translate.rkt

Nieuw en nog untracked:

migrate-cmap-subpages.rkt

Voer dus geen reset, checkout of brede formattering uit voordat deze wijzigingen zijn beoordeeld en veilig gecommitte. wiki-data/ en compiled/ zijn lokale/gegenereerde directories en staan in .gitignore.

Snel starten

Benodigd:

• Racket met de dependencies uit info.rkt (crypto-lib, db-lib, net-lib, net-cookies-lib, openssl-lib en web-server-lib);
• PostgreSQL; de database moet vooraf bestaan en de opgegeven rol moet tabellen en indexen mogen maken;
• internettoegang tijdens de eerste setup om de vastgepinde browserbibliotheken te downloaden.

In deze ontwikkelomgeving is Racket 9.1 gebruikt. Start vanuit de projectroot:

racket main.rkt --data ./wiki-data --port 8080

Open daarna http://127.0.0.1:8080/. Een incomplete installatie gaat automatisch naar /setup. Daar worden de databaseverbinding, migraties, frontendbestanden en eerste administrator geregeld. Luisteren op alle interfaces kan met:

racket main.rkt --data ./wiki-data --listen '*' --port 8080

Gebruik achter HTTPS altijd --secure-cookie. Andere relevante opties zijn --title, --language en|nl en de hersteloptie --create-admin USER PASSWORD.

De database-instellingen, inclusief eventueel het wachtwoord, staan in wiki-data/database.rktd. Dit bestand hoort niet in Git of in logs. De applicatie probeert het bestand met mode 0600 aan te maken.

Als alleen de browserdependencies hersteld moeten worden:

racket setup-vendor.rkt --data ./wiki-data

Codekaart

Pad	Verantwoordelijkheid
main.rkt	CLI en programmatische entrypoints start en start-wiki
server.rkt	HTTP-routering, setup/loginpagina's en alle JSON/API-handlers
private/config.rkt	runtimeconfiguratie en paden onder de datadirectory
private/setup.rkt	eerste websetup en herstelcontrole
private/database.rkt	PostgreSQL-configuratie, verbindingen en migratiestart
private/migrations.rkt	geordende, transactionele databaseschemamigraties
private/storage.rkt	pagina's, historie, zoeken, todo's, bookmarks, aliassen en uploads
private/cmap-storage.rkt	opslag, historie, zoeken en gebruikstellingen voor CMaps
private/auth.rkt	wachtwoorden, sessies, CSRF, rollen en password-reset-tokens
private/mail.rkt	SMTP-instellingen en resetmails
translate.rkt	Engelse/Nederlandse server- en frontendvertalingen
static/index.html	skelet van de ingelogde single-page-interface
static/js/wiki.js	applicatiestatus, API-calls, pagina-editor en CMap-hostintegratie
static/cmap/	lokaal onderhouden CMap-renderer, editorlaag en styling
architecture/	importeerbare Nederlandse architectuurpagina's en twee CMaps
scrbl/racket-wiki.scrbl	package/API-documentatie in Scribble

De browserfrontend heeft bewust geen buildstap. Wijzig bronbestanden rechtstreeks en test ze in de browser. Externe browserlibraries staan runtime onder wiki-data/static/vendor/; wijzig die niet als applicatiebron.

Belangrijke invarianten

• Er is geen anonieme wiki-toegang. reader leest, editor schrijft en admin beheert gebruikers en instellingen.
• Schrijvende API-calls vereisen naast een sessie ook de CSRF-token.
• Pagina's hebben een aparte namespace en stabiele slug; de combinatie is uniek. Een titelwijziging verandert de slug niet.
• Elke paginasave wijzigt pages en schrijft in dezelfde transactie een onveranderlijke page_versions-rij.
• Pagina-updates en CMap-updates gebruiken optimistic locking en horen bij een verouderde basisversie HTTP 409 te geven.
• Pagina's en CMaps worden gearchiveerd (soft delete); histories blijven behouden.
• Bijlagen staan als BYTEA in PostgreSQL. Alleen vertrouwde rasterformaten worden inline geserveerd; andere bestanden worden downloads.
• Markdown gaat vóór invoegen in de DOM door DOMPurify.
• Verhoog current-schema-version alleen samen met een nieuwe, opeenvolgende migratie. Een database met een nieuwer schema dan de code moet geweigerd blijven.

Lopend werk: 0.2.95–0.2.99

De niet-gecommitte reeks bouwt vooral de persistente CMap-functionaliteit uit:

• stabiele, wiki-brede conceptId-identiteiten en gekoppelde plaatsingen met een eigen layout;
• conceptaspecten, beschrijvingspagina's, stijlpresets, afzonderlijke titel-/synopsisopmaak en een bewerkbaar kleurenpalet;
• directe relaties met Alt, gelinkte copy/paste en robuust herstel bij relaties met ontbrekende eindpunten;
• afgeleide, opgeslagen sub-CMapweergaven die naar de canonieke parentgraph verwijzen;
• keuze van een start-CMap en per-view verborgen concepten;
• autosave zonder historievervuiling, maximaal vijf handmatige saves en onbeperkte snapshots;
• verwijderen van afzonderlijke handmatige CMap-history-items/snapshots;
• een paneel op wikipagina's met alle gekoppelde CMap-concepten en plaatsingstellingen.

Migratie 12 schoont oude CMap-autosavehistorie op en beperkt herkenbare handmatige saves tot vijf. migrate-cmap-subpages.rkt is een aparte contentmigratie voor oudere inline sub-CMaps; dit is geen databaseschemamigratie.

Gebruik die contentmigratie altijd eerst als dry-run:

racket migrate-cmap-subpages.rkt --data ./wiki-data
racket migrate-cmap-subpages.rkt --data ./wiki-data --apply

Zonder --apply wordt niets gewijzigd. Met --apply gebeurt de omzetting in één PostgreSQL-transactie. Maak desondanks eerst een databasebackup en beoordeel de gemelde slugs.

Testen en huidige verificatiestatus

De automatische testdekking is beperkt. Op 22 augustus 2026 zijn de volgende controles succesvol uitgevoerd:

raco test architecture/import.rkt
# 12 tests passed

raco make main.rkt server.rkt setup-vendor.rkt \
  migrate-cmap-subpages.rkt architecture/import.rkt

node --check static/js/wiki.js
node --check static/js/combobox.js
node --check static/cmap/cmap.js
node --check static/cmap/cmap-racket-wiki.js

Er is nog geen geautomatiseerde backendintegratietest tegen PostgreSQL en geen browsertestsuite. De huidige 0.2.95–0.2.99-werkboom is dus wel compileerbaar en syntactisch geldig, maar nog niet in deze overdracht end-to-end gevalideerd.

Voer vóór commit/release minimaal deze smoke tests uit op een kopie of aparte testdatabase:

1. Verse /setup, login/logout en de drie rollen.
2. Pagina maken, wijzigen, hernoemen, history bekijken, conflict (409), namespace-link en upload.
3. CMap maken, autosave, expliciet opslaan, snapshot maken/verwijderen en historylimiet controleren.
4. Een concept meerdere keren en in meerdere CMaps plaatsen; controleer tellingen en het paneel op de gekoppelde wikipagina.
5. Een inline sub-CMap met de dry-run en daarna --apply migreren; controleer parent, derived view en oude histories.
6. Start-CMap, verborgen concepten, linked copy/paste, undo/redo en beschadigde relatie zonder endpoint controleren.
7. Zoekresultaten, bookmarks, todo's, aliassen en adminoverzichten nalopen.
8. Indien mail relevant is: SMTP-test en de volledige vergeten-wachtwoordflow.

Architectuurdocumentatie importeren

Valideren en wijzigingen vooraf bekijken:

racket architecture/import.rkt --data ./wiki-data --dry-run

Importeren:

racket architecture/import.rkt --data ./wiki-data --author "Naam ontwikkelaar"

De import is herhaalbaar en gebruikt source hashes. Lokaal aangepaste geïmporteerde pagina's/CMaps worden standaard overgeslagen. Gebruik --overwrite-modified alleen na controle van hun histories.

Mailconfiguratie

Password-resetmail kan via de admininterface/database of via omgevingsvariabelen worden ingesteld. Ondersteund zijn:

RACKET_WIKI_PUBLIC_URL
RACKET_WIKI_SMTP_HOST
RACKET_WIKI_SMTP_PORT
RACKET_WIKI_SMTP_FROM
RACKET_WIKI_SMTP_USER
RACKET_WIKI_SMTP_PASSWORD
RACKET_WIKI_SMTP_TLS
RACKET_WIKI_SMTP_ACCEPT_UNTRUSTED_CERTIFICATES
RACKET_WIKI_RESET_LIMIT

Accepteer onbetrouwbare certificaten alleen bewust voor een vertrouwde lokale SMTP-server. Zet secrets nooit in documentatie, commits of testoutput.

Aanbevolen eerstvolgende stap

Maak eerst een databasebackup en test de volledige niet-gecommitte 0.2.95–0.2.99-reeks met bovenstaande smoke tests. Beoordeel daarna de diff als één samenhangende CMap-wijziging, werk zo nodig README.md, Scribble-documentatie en architectuurpagina's gelijk bij, en commit pas wanneer migratie 12 en migrate-cmap-subpages.rkt op representatieve data zijn geverifieerd.

Voor functionele details en releasehistorie is README.md de uitgebreidste bron. De bestanden onder architecture/pages/ beschrijven ontwerpbeslissingen en kwaliteitsafspraken; architecture/pages/code-regels.md is de beste start voor projectconventies.