# 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.