Begrippen

Korte uitleg per begrip, in de volgorde waarin je ze tegenkomt: eerst het product, dan de techniek eronder, dan de infrastructuur. Namen in code zijn Engels; het proza in deze documentatie is Nederlands.

Het product

Tenant. Eén klant op het platform, met een eigen site, eigen database en eigen domein. In code heet een klant altijd tenant; de korte naam (slug, bijvoorbeeld rb-media) komt overal terug: in de databasenaam tenant_rb-media, de omgevingsvariabele TENANT_ID en het preview-adres.

Klantsite / site-template. De website van een klant. In de repo is dat één app, apps/site-template, die voor elke klant apart wordt gedraaid met andere omgevingsvariabelen. “Template” betekent hier dus niet “sjabloon om te kopiëren”, maar “dezelfde app, andere gegevens”.

CMS. Content Management System: de beheeromgeving waarin de klant zelf teksten, afbeeldingen en pagina’s beheert. Het CMS is onderdeel van dezelfde app als de publieke site en draait op het subdomein admin.<domein>.

Master dashboard. De centrale beheeromgeving van de platformbeheerder (apps/master-dashboard). Registreert klanten, rolt sites uit, koppelt domeinen en toont activiteit. Eén installatie voor alle klanten.

Blok. Een bouwsteen van een pagina: een hero, een tekst, een afbeelding, een call-to-action, een rij kaarten, een citaat. Een pagina is niets anders dan een geordende lijst blokken. Elk blok heeft een type, een id en props (de inhoud).

Blokkenbibliotheek. De verzameling beschikbare bloktypen met per blok een schema (wat mag erin), een renderer (hoe ziet het eruit) en een registratie (dat het bestaat). Package packages/blocks.

Huisstijl / theme / design tokens. De kleuren, lettertypes, hoekafrondingen en spacing van een klant. Opgeslagen als gegevens (site.theme), bij het renderen omgezet naar CSS-variabelen. “Design tokens” is de vakterm voor zulke benoemde ontwerpwaarden. Componenten bevatten nooit een vaste kleur; ze verwijzen naar een token.

Provisioning. Het uitrollen van een nieuwe klant: database aanmaken, schema erin zetten, geheimen genereren, een applicatie bij de hostingpartij aanmaken en starten. In het dashboard is dat de knop Provisioneren.

Preview-domein. Het adres dat elke klant meteen na provisioning krijgt, <slug>.preview.okhema.studio, met het CMS op admin.<slug>.preview.okhema.studio. Werkt zonder dat de klant iets aan zijn eigen domein hoeft te doen.

Custom domain. Het eigen domein van de klant (www.klant.nl), later gekoppeld via Cloudflare for SaaS. De klant zet een CNAME-record; certificaten regelt Cloudflare.

De techniek eronder

Monorepo. Eén Git-repository met meerdere apps en packages die samen worden beheerd. Hier met pnpm workspaces (installatie en koppeling tussen packages) en Turborepo (taken zoals build en typecheck over alles tegelijk draaien).

Contract. Het gedeelde package @platform/contract met alle types en Zod-schema’s die zowel de klantsite als het master dashboard gebruiken. Eén definitie, twee gebruikers, dus geen verschillen tussen beide kanten. Ook de naam van het document dat beschrijft hoe dashboard en sites met elkaar praten.

Zod. Bibliotheek om gegevens te valideren tegen een schema. Alles wat als JSON in de database gaat (blokken, theme, instellingen) wordt bij schrijven én lezen door een Zod-schema gehaald.

jsonb. Het Postgres-kolomtype voor JSON-gegevens. Blokken en theme staan als jsonb in de database.

Drizzle. De bibliotheek waarmee de code met Postgres praat (een ORM). Drizzle Kit genereert uit het schema in code de SQL-migraties.

Migratie. Een SQL-bestand dat de databasestructuur een stap verder brengt (tabel erbij, kolom erbij). Migraties staan in de repo en worden op elke tenant-database in dezelfde volgorde uitgevoerd.

Database-per-tenant. Elke klant een eigen Postgres-database met een eigen databasegebruiker. Volledige isolatie; een fout in een query kan nooit gegevens van een andere klant raken.

Astro. Het webframework van de klantsite. Draait hier server-side (SSR: elke pagina wordt bij een bezoek op de server opgebouwd), zodat een publicatie in het CMS direct zichtbaar is zonder herbouw.

Route-cache. Astro’s ingebouwde cache van complete pagina-antwoorden. Een tweede bezoeker krijgt de opgeslagen HTML; de database wordt niet geraakt. Publiceren in het CMS maakt de betrokken pagina’s expliciet leeg (“purgen”).

Nuxt. Het webframework (Vue) van het master dashboard.

Tailwind. CSS-utilityklassen zoals bg-primary en rounded-md. In de klantsite verwijzen die klassen naar de theme-variabelen van de klant, niet naar vaste waarden.

Better Auth. De authenticatiebibliotheek voor inloggen en sessies, zowel in het CMS (rollen admin en editor) als in het master dashboard.

Webhook. Een HTTP-bericht dat de ene applicatie naar de andere stuurt zodra er iets gebeurt. Klantsites sturen webhooks naar het master dashboard: content gepubliceerd, formulier ontvangen, gebruiker ingelogd.

HMAC. Een handtekening over een bericht, gemaakt met een gedeeld geheim. Elke webhook draagt zo’n handtekening, zodat de ontvanger zeker weet van welke site hij komt en dat er niets aan is veranderd.

Outbox. Een tabel waarin uitgaande webhooks bewaard blijven als het versturen mislukt, om het later opnieuw te proberen. Zo verliest de site nooit een gebeurtenis en wacht een bezoeker nooit op het dashboard.

Idempotent. Een bewerking die je veilig vaker kunt uitvoeren met hetzelfde resultaat. Provisioning is idempotent (een tweede keer klikken herstelt alleen wat nog mist) en webhook-ontvangst ook (dezelfde gebeurtenis wordt niet twee keer geteld).

De infrastructuur

VPS. De gehuurde server (bij Hetzner) waarop alles draait.

Docker / container. Elke klantsite draait als een eigen container: een afgeschermd proces met zijn eigen omgevingsvariabelen. Eén Docker-image (het gebouwde pakket) dient alle klanten; alleen de omgevingsvariabelen verschillen.

Coolify. Het self-hosted platform op de VPS dat containers, domeinen, certificaten en databasebackups beheert. Het master dashboard praat via de Coolify-API om nieuwe klant-apps aan te maken en te starten.

Traefik. De reverse proxy (het “verkeersbord”) vóór alle containers. Kijkt naar de hostname van een verzoek en stuurt het naar de juiste container; regelt ook de TLS-certificaten via Let’s Encrypt.

Cloudflare. DNS-beheer van okhema.studio, en met Cloudflare for SaaS de dienst die klantdomeinen met automatische certificaten aan het platform koppelt.

DNS-01 / HTTP-01. Twee manieren waarop Let’s Encrypt controleert dat je een domein bezit. DNS-01 is nodig voor wildcard-certificaten zoals *.preview.okhema.studio.

S3 / R2 / B2 / MinIO. Object storage voor media (afbeeldingen). S3 is de API-standaard; Cloudflare R2 is de productie-opslag, Backblaze B2 de backup-replica, MinIO de lokale variant in Docker.

Resend. De dienst die e-mails verstuurt (contactformulier, wachtwoordherstel).

Umami. Self-hosted websitestatistieken. Gepland voor fase 4.

Puck. Open-source pagebuilder-component. Gepland voor fase 3, bovenop het bestaande blokmodel.