cmap functions, email, architecture documentation.

2026-08-18 03:33:10 +02:00
parent 12f1ed2764
commit 63b7ca0853
33 changed files with 3974 additions and 80 deletions
@@ -0,0 +1,67 @@
+# Structuur en samenhang
+
+## Context
+
+racket-wiki bestaat tijdens normaal gebruik uit drie uitvoerende delen:
+
+| Deel | Verantwoordelijkheid |
+| --- | --- |
+| Browser | Navigatie, lokale UI-toestand, EasyMDE, Markdownweergave, CMap-bewerking en grafische relaties |
+| Racket-proces | HTTP-routing, sessies, rollen, CSRF, validatie, opslagorkestratie, setup en statische bestanden |
+| PostgreSQL | Duurzame toestand, relationele integriteit, transacties, historie, zoekindexen en binaire bijlagen |
+
+Er is geen afzonderlijke Node-server, Markdownservice of object store. Na setup worden frontendbibliotheken lokaal door hetzelfde Racket-proces geserveerd.
+
+## Bronstructuur
+
+`main.rkt` is het programma- en bibliotheekingangspunt. Het bouwt een `wiki-config`, initialiseert zo nodig de database en start `server.rkt`.
+
+`server.rkt` vormt de HTTP-adapter. Het koppelt URL's en methoden aan handlers, vertaalt requests naar domeinbewerkingen en vertaalt resultaten of fouten naar HTML/JSON-responses. Setup, login en wachtwoordherstel zijn server-rendered; de normale wiki is een single-page browserapplicatie.
+
+De map `private/` bevat de backendonderdelen:
+
+| Module | Hoofdtaak |
+| --- | --- |
+| `config.rkt` | Runtimeconfiguratie en paden |
+| `database.rkt` | PostgreSQL-instellingen, verbinding en initialisatie |
+| `migrations.rkt` | Opeenvolgende, transactionele schemasprongen |
+| `auth.rkt` | Gebruikers, wachtwoorden, rollen, sessies, CSRF en herstelcodes |
+| `storage.rkt` | Pagina's, historie, zoeken, bookmarks, uploads en aliases |
+| `cmap-storage.rkt` | Conceptmaps en onveranderlijke CMap-versies |
+| `attachment-references.rkt` | Huidige en historische verwijzingen naar bijlagen |
+| `todo.rkt` | Herkennen van wiki-brede `todo(...)`-markeringen |
+| `mail.rkt` | SMTP-instellingen, STARTTLS, testmail en herstelmail |
+| `setup.rkt` | Eerste websetup en reparatiepad |
+| `vendor.rkt` | Ophalen en controleren van vastgepinde browserbibliotheken |
+| `http-util.rkt` | Gemeenschappelijke response- en requesthulpen |
+| `version.rkt` | Softwareversie uit `info.rkt` |
+
+`translate.rkt` staat bewust aan de publieke rand: zowel backend als frontend gebruiken dezelfde effectieve vertaaltabel.
+
+De map `static/` bevat de browserapplicatie. `static/index.html` definieert de views en dialogen. `static/js/wiki.js` beheert routing, API-aanroepen, editor- en paginatoestand en speciale views. `static/cmap/cmap.js` levert de grafische basis; `cmap-racket-wiki.js` voegt wiki-items, selectie, relaties, sub-CMaps, historie en documentserialisatie toe. `combobox.js` is een herbruikbaar klein UI-onderdeel. CSS is verdeeld tussen algemene wiki-opmaak en CMap-opmaak.
+
+## Afhankelijkheidsrichting
+
+De bedoelde richting is:
+
+1. `main.rkt` kent configuratie, database-initialisatie en server.
+2. `server.rkt` kent backenddiensten, maar backendopslag kent geen HTTP-requests.
+3. Opslagmodules kennen `database.rkt` en dataconversies, maar geen browserdetails.
+4. De browser kent alleen HTTP-contracten en de CMap-component; hij kent geen SQL.
+5. PostgreSQL kent alleen schema en constraints; het kent geen HTML of routes.
+
+Deze richting houdt de belangrijkste domeinregels buiten de UI. Een rolcontrole die uitsluitend een knop verbergt, is bijvoorbeeld onvoldoende: `server.rkt` moet dezelfde bewerking weigeren.
+
+## Samenhang via hoofdgegevens
+
+Een pagina heeft een database-id, namespace, slug, actuele Markdown en een versieteller. `page_versions` verwijst naar dezelfde pagina-id. Todo's, bookmarks, aliases en bijlageverwijzingen sluiten via die id aan.
+
+Een CMap heeft een stabiele slug, titel, JSONB-document en versieteller. `concept_map_versions` bewaart volledige JSONB-snapshots. CMap-items kunnen via `pageSlug` naar een wikipagina verwijzen en via `cmapSlug` naar een andere CMap. De browser gebruikt deze verwijzingen voor navigatie en de gecombineerde sitegraph.
+
+Zie [Data, transacties en versiebeheer](racket-wiki:data-en-versies) voor de invarianten en [Modulariteit en afhankelijkheden](racket-wiki:modulariteit) voor de gewenste grenzen bij uitbreiding.
+
+## Deploymentstructuur
+
+De installatie bevat code en statische basisbestanden. De configureerbare datamap bevat `database.rktd`, de gekozen taal en lokaal gedownloade vendor-assets. Inhoud en bijlagen staan in PostgreSQL. Daardoor moet een volledige back-up zowel de database als de kleine datamap met configuratie bevatten.
+
+De Racket-server kan rechtstreeks luisteren, maar in productie ligt HTTPS gewoonlijk bij een reverse proxy. `secure-cookie?` moet dan aan staan en de publieke URL voor herstelmail moet naar de externe HTTPS-URL wijzen.