racket-wiki/architecture/pages/gedrag.md

Gedrag en hoofdscenario's

Deze pagina beschrijft gedrag als ketens van waarneembare stappen. De backend blijft in iedere keten verantwoordelijk voor autorisatie en duurzame invarianten; browserstatus is slechts tijdelijke presentatietoestand.

Start en eerste setup

1. main.rkt maakt de datamap aan en leest database.rktd wanneer die bestaat.
2. Bij bekende database-instellingen voert initialize-database! alle nog ontbrekende migraties in volgorde uit en verwijdert het verlopen sessies.
3. server.rkt controleert of schema, een ingeschakelde administrator en alle vendor-assets aanwezig zijn.
4. Zolang een voorwaarde ontbreekt, gaan normale requests naar /setup.
5. Setup test PostgreSQL, installeert het schema, maakt de eerste administrator en downloadt de vastgepinde frontendbestanden.
6. Na een volledige setup gaat de browser naar /login.

Setup is daarmee ook een reparatiepad voor ontbrekende browserassets. Het is geen anonieme route naar wiki-inhoud.

Aanmelden en een request uitvoeren

Bij succesvolle authenticatie genereert de backend een willekeurig sessietoken en CSRF-token. Alleen de SHA-256-hash van het sessietoken staat in PostgreSQL; het ruwe token gaat in de cookie naar de browser. Iedere API-handler die inhoud schrijft vereist een geldige sessie, voldoende rol en het CSRF-token uit die sessie.

reader leest. editor erft lezen en mag pagina's en CMaps creëren, wijzigen, archiveren en bestanden uploaden. admin erft editorrechten en beheert gebruikers en systeeminstellingen.

Pagina lezen

1. De browser haalt eerst de paginacatalogus op zonder alle Markdown.
2. Navigatie naar een pagina vraagt de actuele pagina met Markdown op.
3. Namespaced links en WikiWords worden naar interne routes vertaald.
4. EasyMDE/Marked rendert dezelfde Markdown voor leesweergave, preview en historische versies.
5. DOMPurify saneert de HTML voordat zij in het document komt.
6. Fenced code wordt met highlight.js gemarkeerd en {{cmap:slug}} wordt daarna met een read-only CMap gehydrateerd.

Een dubbelklik op een ingebedde CMap opent de volledige editor. De ingesloten kaart is niet een tweede opslagvorm.

Pagina maken of wijzigen

Een nieuwe pagina krijgt een namespace en stabiele slug. Bij opslaan stuurt de browser titel, Markdown, tags en bij een bestaande pagina het bekende currentVersion mee.

De opslagmodule vergrendelt de actuele rij binnen een PostgreSQL-transactie. Alleen als de meegestuurde basisversie gelijk is aan de databaseversie worden actuele toestand, nieuwe onveranderlijke versie, todo-index en bijlageverwijzingen samen vastgelegd. Is iemand anders eerder geweest, dan volgt version-conflict; de oudere editor mag de nieuwere versie niet stilzwijgend overschrijven.

Hernoemen of verplaatsen behoudt dezelfde pagina-id en maakt een alias voor het oude adres. Archiveren verwijdert de pagina niet fysiek en behoudt historie en bijlagen.

Conceptmap bewerken

De CMap-editor houdt items, verbindingszinnen, connectors, groepen en sub-CMaps in één document met schemaVersion: 1. Bewerkingen gaan eerst door een lokale Undo/Redo-historie. Na een afgeronde handeling plant de browser een autosave; een nieuwe handeling verschuift die timer. Een lopende save kan een volgende save noodzakelijk maken, zodat tussentijdse wijzigingen niet verdwijnen.

Iedere serveropslag controleert opnieuw het basisversienummer en schrijft een volledige CMap-snapshot. Autosave beschermt de werkstand. Snapshot maken schrijft ook zonder inhoudsverschil een herkenbaar historisch moment met een omschrijving. Een historische versie laden verandert alleen de editor; pas een volgende opslag maakt daarvan een nieuwe actuele versie.

Zoeken, Recent en navigatiegraaf

Paginazoeken gebruikt een opgeslagen gewogen tsvector en GIN-index. CMap-zoeken verzamelt titel, slug, labels en synopses uit JSONB. Recent voegt de nieuwste pagina- en CMapwijzigingen samen.

De gecombineerde navigatiegraaf leest verwijzingen uit alle huidige pagina's en CMaps. Hij wordt in de browser gecachet totdat een catalogus opnieuw wordt geladen. Dit levert rijke navigatie op, maar is het belangrijkste schaalrisico; zie Verwachte performance.

Wachtwoordherstel en mail

De publieke herstelactie geeft altijd dezelfde reactie, ook als een account niet bestaat. Een echte aanvraag maakt een gehashte, eenmalige code die één uur geldig is en past rate limiting per gebruiker toe. Na succesvol herstel worden bestaande sessies ingetrokken.

SMTP kan STARTTLS gebruiken. Standaard gebruikt mail ssl-secure-client-context en controleert certificaatketen en hostnaam. Alleen voor een bewust vertrouwde lokale server kan de administrator onvertrouwde certificaten accepteren; dan gebruikt de verbinding moderne TLS zonder serverauthenticatie. De testmail gebruikt eerst de nog niet opgeslagen formulierwaarden.

Foutgedrag

Verwachte domeinfouten worden zo dicht mogelijk bij hun grens herkend: ongeldige input als 400, ontbrekende authenticatie als 401, onvoldoende rechten als 403, ontbrekende inhoud als 404 en versieconflict als 409. Technische uitzonderingen moeten voldoende context in de serverconsole behouden zonder wachtwoorden, tokens of databasegeheimen te loggen.