53 lines
4.4 KiB
Markdown
53 lines
4.4 KiB
Markdown
# Architectuur van racket-wiki
|
|
|
|
Deze documentatieset beschrijft de architectuur van racket-wiki zoals die in versie 0.2.94 bestaat. Zij is tegelijk een wegwijzer voor onderhoud: iedere pagina maakt onderscheid tussen bestaand gedrag, bekende grenzen en regels voor verdere ontwikkeling.
|
|
|
|
{{cmap:racket-wiki-architectuur}}
|
|
|
|
## Architectuur in één alinea
|
|
|
|
racket-wiki is een kleine, zelf gehoste webapplicatie. Eén Racket-proces levert de HTTP-server, authenticatie, autorisatie, setup, databaseaanroepen en statische bestanden. PostgreSQL bevat de duurzame toestand: gebruikers, sessies, pagina's, onveranderlijke paginaversies, conceptmaps, CMap-versies, bijlagen en beheerinstellingen. De browser bevat de interactieve applicatie, Markdown-editor en CMap-editor. De grens tussen browser en backend is een JSON/HTTP-API. Normaal gebruik vereist geen externe CDN of afzonderlijke applicatieservice.
|
|
|
|
## Leeswijzer
|
|
|
|
| Onderwerp | Vraag die de pagina beantwoordt |
|
|
| --- | --- |
|
|
| [Structuur en samenhang](racket-wiki:structuur-en-samenhang) | Welke onderdelen zijn er en hoe zijn zij verbonden? |
|
|
| [Gedrag en hoofdscenario's](racket-wiki:gedrag) | Wat gebeurt er bij starten, lezen, wijzigen en herstellen? |
|
|
| [Data, transacties en versiebeheer](racket-wiki:data-en-versies) | Welke toestand wordt waar bewaard en welke invarianten gelden? |
|
|
| [Modulariteit en afhankelijkheden](racket-wiki:modulariteit) | Waar liggen de modulegrenzen en waar zitten risico's? |
|
|
| [Onderhoudbaarheid](racket-wiki:onderhoudbaarheid) | Hoe blijft de code begrijpelijk en wijzigbaar? |
|
|
| [Analyseerbaarheid en diagnose](racket-wiki:analyseerbaarheid) | Hoe wordt een storing of regressie gelokaliseerd? |
|
|
| [Testbaarheid en teststrategie](racket-wiki:testbaarheid) | Welke tests passen bij welke laag? |
|
|
| [Verwachte performance](racket-wiki:performance) | Waar schaalt het ontwerp goed en waar ontstaan knelpunten? |
|
|
| [Beveiliging en vertrouwen](racket-wiki:beveiliging) | Welke vertrouwensgrenzen en beveiligingsmaatregelen bestaan? |
|
|
| [Regels bij het coderen](racket-wiki:code-regels) | Welke concrete ontwerp- en stijlregels gelden voor nieuwe code? |
|
|
| [Beheer en evolutie](racket-wiki:beheer-en-evolutie) | Hoe worden schema, frontend-assets en architectuur gewijzigd? |
|
|
|
|
{{cmap:racket-wiki-kwaliteitskenmerken}}
|
|
|
|
## Belangrijkste architectuurbeslissingen
|
|
|
|
De huidige vorm rust op een klein aantal bewuste keuzes:
|
|
|
|
1. PostgreSQL is de enige duurzame inhoudsopslag. Ook bijlagen staan als `BYTEA` in de database.
|
|
2. Huidige pagina's en CMaps zijn snel leesbare projecties; iedere opslag maakt daarnaast een volledige, onveranderlijke versie.
|
|
3. Schrijven gebeurt met optimistic locking. De browser moet het bekende versienummer meesturen.
|
|
4. De backend bepaalt authenticatie, rollen, CSRF-controle en database-invarianten. De browser is niet de beveiligingsgrens.
|
|
5. Markdown wordt in de browser gerenderd en daarna met DOMPurify gesaneerd.
|
|
6. Browserbibliotheken worden tijdens setup vastgepind en lokaal geserveerd.
|
|
7. Pagina-adressen bestaan uit een namespace en stabiele slug. Deze set gebruikt de namespace `racket-wiki`.
|
|
8. Conceptmaps blijven native CMap-documenten. `{{cmap:...}}` sluit een read-only weergave in Markdown in zonder het CMap-formaat tot Mermaid te reduceren.
|
|
|
|
## Kwaliteitsbeeld
|
|
|
|
De architectuur past goed bij een persoonlijke of teamwiki: weinig processen, een duidelijke databasebron en volledige historie. De sterkste punten zijn de transactionele inhoudsopslag, eenvoudige deployment en lokale frontend-assets. De voornaamste ontwikkelpunten zijn de omvang van `server.rkt` en `static/js/wiki.js`, het ontbreken van een volwaardige geautomatiseerde testsuite, een nieuwe databaseverbinding per opslagbewerking en de N+1-aanpak waarmee de volledige navigatiegraaf wordt opgebouwd.
|
|
|
|
Deze punten zijn geen reden voor een voorafgaande grote herbouw. De ontwikkelregel is: meet eerst, isoleer het concrete probleem en splits een module wanneer een wijziging daar aantoonbaar eenvoudiger of beter testbaar door wordt.
|
|
|
|
## Eigenaarschap van deze documentatieset
|
|
|
|
De bestanden onder `architecture/` zijn de bron van deze set. De importmodule plaatst een bronmarkering in iedere geïmporteerde pagina en CMap. Een herimport werkt alleen automatisch bij als de geïmporteerde inhoud sindsdien niet handmatig is gewijzigd. Lokale wijzigingen worden standaard behouden en gerapporteerd.
|
|
|
|
Gebruik [Beheer en evolutie](racket-wiki:beheer-en-evolutie) voor de importprocedure en de regels om deze documentatie gelijk te laten lopen met de code.
|