4.5 KiB
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:
main.rktkent configuratie, database-initialisatie en server.server.rktkent backenddiensten, maar backendopslag kent geen HTTP-requests.- Opslagmodules kennen
database.rkten dataconversies, maar geen browserdetails. - De browser kent alleen HTTP-contracten en de CMap-component; hij kent geen SQL.
- 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 voor de invarianten en Modulariteit en afhankelijkheden 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.