70 lines
5.6 KiB
Markdown
70 lines
5.6 KiB
Markdown
# 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, gedeelde conceptdefinities, onveranderlijke CMap-versies en opgeslagen SVG-weergaven |
|
|
| `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 routedispatch, API-aanroepen, editor- en paginatoestand en speciale views. De modules onder `static/js/wiki/` bevatten afzonderlijk de referentiesyntaxis, routeherkenning, Markdowntransformaties, paginakoppen en breadcrumbhistorie. De controllers onder `static/js/wiki/admin/` beheren ieder één administratief formulier of overzicht; routes, permissiecontrole, breadcrumbs en algemene adminnavigatie blijven in `wiki.js`.
|
|
|
|
De generieke CMap-component staat onder `static/js/cmap/`. `cmap.js` levert de tekenengine. `cmap-racket-wiki.js` is de wiki-editorfacade en composeert document-, geometrie-, relatie-, layout-, selectie-, interactie- en submapcontrollers. De views voor itemdecoratie, grensverwijzingen en SVG-snapshots houden presentatie buiten het model. De wiki-specifieke hostlaag staat onder `static/js/wiki/cmap/`: `CmapWorkspaceController` bouwt afhankelijkheden en registreert DOM-events; `CmapEditorHost`, `CmapEditorUiController`, `CmapStorageController`, `CmapNavigationController`, `CmapTransferController`, `CmapMapController` en `CmapConceptController` bezitten ieder hun eigen workflow. `CmapEmbedView` toont opgeslagen SVG-renders in Markdown en `CmapEditorPresentation` levert editorpresentatie en gebruikstellingen. 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_renders` bewaart de actuele SVG-weergave per documentversie apart. CMap-items kunnen via `pageSlug` naar een wikipagina verwijzen en via `cmapSlug` naar een andere CMap. De browser gebruikt deze verwijzingen om het gekoppelde doel rechtstreeks te openen.
|
|
|
|
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.
|