hans/racket-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

documentatie

Browse Source
This commit is contained in:
Hans Dijkema
2026-09-03 17:24:56 +02:00
parent e971dfe942
commit 42fcea9af8
14 changed files with 135 additions and 16 deletions
Download Patch File Download Diff File Expand all files Collapse all files
architecture/pages/architectuur.md
+6 -4
View File
@@ -1,12 +1,12 @@
# 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.
Deze documentatieset beschrijft de architectuur van racket-wiki zoals die in versie 0.2.122 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.
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, gedeelde conceptdefinities, opgeslagen SVG-weergaven, bijlagen en beheerinstellingen. De browser bevat de interactieve applicatie, Markdown-editor en modulaire CMap-editor. De grens tussen browser en backend is een JSON/HTTP-API. Normaal gebruik vereist geen externe CDN of afzonderlijke applicatieservice.
## Leeswijzer
@@ -37,11 +37,13 @@ De huidige vorm rust op een klein aantal bewuste keuzes:
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.
8. Conceptmaps blijven native CMap-documenten. `{{cmap:...}}` sluit een opgeslagen SVG-weergave als linkbare afbeelding in Markdown in zonder het CMap-formaat tot Mermaid te reduceren.
9. CMap-structuur, gedeelde conceptinhoud en afgeleide SVG-weergave hebben afzonderlijke opslagcontracten. De SVG is geen onderdeel van het bewerkbare CMap-JSON-document.
10. De CMap-editor gebruikt native ES-modules met expliciete model-, controller-, view- en workspacegrenzen. De workspace coördineert alleen editorcallbacks, dialogen en DOM-events.
## 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 en een nieuwe databaseverbinding per opslagbewerking.
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, lokale frontend-assets en de afgebakende CMap-editor. De voornaamste ontwikkelpunten zijn de omvang van `server.rkt` en `static/js/wiki.js`, beperkte backend- en browsertestdekking en een nieuwe databaseverbinding per opslagbewerking.
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.