docs(architecture): import the FDS architecture decisions (refs #159)

Bring the engineer-facing FDS documentation next to the code it describes: ADR-0001 to ADR-0006, the ADR index and template, the L3 component view, and the slice-1 proposal. All translated to Dutch. Source: projects/open-register-fd/ in Respellion/innovation-lab. Land the set in docs/architecture/fds/ rather than docs/architecture/. This repo already owns adr-0001-loose-coupling to adr-0004-bdd-framework, so a flat import collides on every number. The subfolder keeps the imported numbering, and with it about thirty ADR-000N cross-references in the imported text. Add the mermaid custom fence to pymdownx.superfences. Without it the imported diagrams publish as raw code blocks, because the site has no mermaid support today. Add the nav group and one link from the docs index. The blueprint, the FDS gap analysis and the privacy views stay in the lab repo; the OKRs cite them and they feed tender responses. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-09-03 11:27:36 +02:00
parent 28041228bd
commit 334cec0157
12 changed files with 610 additions and 1 deletions
@@ -0,0 +1,42 @@
+# ADR-0001: Anti-Corruption Layer op elke registergrens
+
+- **Status:** accepted
+- **Datum:** 2026-06-13
+- **Deciders:** Lab Circle (Build, Lead Link)
+- **Vervangt / vervangen door:** —
+
+## Context
+
+De applicatie bevraagt meerdere registers: BRP, NHR/KVK, en ZGW via OpenZaak. Hun vocabulaires en
+schema's verschillen van elkaar en van ons domein. Zij veranderen ook zelf mee met de FDS-standaarden.
+
+Lekt registervocabulaire het domeinmodel in, dan werkt elke wijziging aan de registerzijde door in de
+bedrijfslogica. Het domein wordt dan een lappendeken van vreemde begrippen in plaats van ubiquitous
+language.
+
+## Besluit
+
+Elk register is bereikbaar via een Anti-Corruption Layer: **één adapter per register**, die een
+**port** vervult die het domein definieert.
+
+Adapters doen alleen vertalen en velden versmallen. Zij bevatten geen bedrijfslogica. Het domein
+spreekt `Persoon` en `Organisatie`, en nooit veldnamen uit BRP of NHR.
+
+## Gevolgen
+
+**Positief:** verloop in registers en FDS-standaarden blijft bij de adapter. Het domein blijft stabiel
+en testbaar. Adapters zijn onafhankelijk vervangbaar, en dat is precies wat de FSC-wissel uit
+ADR-0002 goedkoop maakt. Het patroon generaliseert naar een herbruikbare ACL-template per register,
+een Foundations-kandidaat.
+
+**Negatief en kosten:** één vertaalmap per register om te schrijven en te onderhouden, plus een extra
+indirectie die engineers moeten respecteren in plaats van omzeilen.
+
+**Vervolgwerk:** extraheer de ACL-template zodra de tweede adapter bestaat (slice 3).
+
+## Overwogen alternatieven
+
+- **Registers direct aanroepen uit de applicatieservices** — afgewezen: dit koppelt bedrijfscode aan
+  registerschema's en aan versies van FDS-standaarden.
+- **Eén generieke registeradapter** — afgewezen: registers verschillen genoeg dat een generieke
+  abstractie zou gaan lekken of opzwellen. Adapters per register zijn duidelijker.
@@ -0,0 +1,44 @@
+# ADR-0002: FSC voor connectiviteit tussen organisaties, geen ruwe REST
+
+- **Status:** accepted
+- **Datum:** 2026-06-13
+- **Deciders:** Lab Circle, Upstream Liaison
+- **Vervangt / vervangen door:** —
+
+## Context
+
+Registerbevragingen kruisen een organisatiegrens naar systemen van bronhouders met
+persoonsgegevens. Het FDS noemt Federatieve Service Connectiviteit (FSC, de opvolger van NLX) als de
+richting voor connectiviteit: wederzijdse authenticatie op organisatieniveau, autorisatie
+gecontroleerd tegen een contract en gehandhaafd bij de bron, en symmetrische transactielogging.
+
+Een ruwe REST-client met mTLS geeft ons geen van de contractadministratie, delegatie of onafhankelijke
+tweezijdige verantwoording die een FG of auditor nodig heeft.
+
+## Besluit
+
+Het FSC Client-component stuurt alle registerbevragingen via een **FSC outway**, de
+EUPL-referentie-implementatie. De ACL-adapter hangt af van de FSC Client, en niet van een HTTP-client.
+
+FSC-zaken — contracten, identiteiten, delegatie — leven in dit component, achter de Register Port.
+
+## Gevolgen
+
+**Positief:** de autorisatie wordt bij de bron gehandhaafd, en niet op gezag van de aanroeper
+vertrouwd. Onweerlegbaar loggen aan beide uiteinden maakt onafhankelijke afstemming tegen ons LDV-log
+mogelijk. Delegatie wordt expliciet meegedragen. Wij lopen in lijn met de FDS-richting, vóór er een
+verplichting is.
+
+**Negatief en kosten:** FSC is operationeel zwaarder dan een REST-aanroep — beheer van certificaten en
+identiteiten, plus een outway die op De Werf moet draaien. De vergelijking FSC tegenover DSP loopt
+binnen het FDS nog, dus sommige details kunnen schuiven.
+
+**Vervolgwerk:** valideer het contract- en logginggedrag van de huidige fsc-nlx-implementatie
+(slice 2). Herzie dit als het FDS voor DSP kiest; ADR-0001 houdt die wissel beperkt tot één component.
+
+## Overwogen alternatieven
+
+- **Ruwe REST met mTLS** — afgewezen: geen contractlaag, geen tweezijdig log, en het wijkt af van het
+  FDS.
+- **Wachten tot het FDS FSC tegenover DSP heeft beslist** — afgewezen: de naad uit ADR-0001 laat ons nu
+  adopteren en later aanpassen. Wachten geeft het voordeel van vroege expertise weg.
@@ -0,0 +1,44 @@
+# ADR-0003: Policy-based access control via OPA, FTV-klaar
+
+- **Status:** accepted
+- **Datum:** 2026-06-13
+- **Deciders:** Lab Circle, FG (geconsulteerd)
+- **Vervangt / vervangen door:** —
+
+## Context
+
+Elke bevraging van persoonsgegevens uit BRP of NHR is een verwerking die een grondslag en een
+begrensde doelbinding nodig heeft. Toegangsregels moeten handhaafbaar en auditeerbaar zijn, en
+wijzigbaar zonder de bedrijfscode opnieuw uit te rollen.
+
+De Federatieve Toegangsverlening (FTV) van het FDS beweegt naar policy-based access control, maar is
+nog geen afgeronde standaard.
+
+## Besluit
+
+Introduceer een Policy Decision Point met Open Policy Agent (OPA). De applicatieservices roepen de
+PDP aan — via een Authorisation Port en een PDP Client — **vóór elke registerbevraging**, en geven
+rol, doel en grondslag mee.
+
+Policies schrijven wij als code, **geversioneerd in Gitea**, en zij gaan via review naar productie. De
+PDP staat zo gepositioneerd dat wij bij de komst van FTV alleen het policy-dialect opnieuw uitdrukken,
+zonder de architectuurgrens te verplaatsen.
+
+## Gevolgen
+
+**Positief:** doelbinding en grondslag worden gehandhaafd, en niet alleen gedocumenteerd. De FG kan de
+werkelijke regels in versiebeheer lezen, waardoor het verwerkingenregister en de gehandhaafde policy
+naar elkaar toe groeien. Toegangswijzigingen zijn reviewbaar en gedateerd.
+
+**Negatief en kosten:** BRP-autorisatiebesluiten correct modelleren is juridisch werk, geen
+engineering. De PDP maakt de handhaving betrouwbaar, niet de policy juist. Daarnaast komt er een
+component bij om te exploiteren.
+
+**Vervolgwerk:** een promotiepijplijn voor policies in Gitea Actions. Policies opnieuw uitdrukken zodra
+FTV stabiliseert. Een FG-review van de policy-set vóórdat er echte persoonsgegevens in komen.
+
+## Overwogen alternatieven
+
+- **Rolcontroles in de applicatiecode** — afgewezen: niet auditeerbaar, niet wijzigbaar zonder deploy,
+  en het verspreidt toegangslogica over de codebase.
+- **Wachten op FTV** — afgewezen: de PBAC-vorm is al duidelijk. Nu OPA, later het FTV-dialect.
@@ -0,0 +1,48 @@
+# ADR-0004: Begrensde cache; registers blijven systeem van registratie
+
+- **Status:** accepted
+- **Datum:** 2026-06-13
+- **Deciders:** Lab Circle, FG (geconsulteerd)
+- **Vervangt / vervangen door:** —
+
+## Context
+
+*Data bij de bron* verbiedt het behandelen van registerdata als lokale bron van waarheid. Maar BRP of
+NHR bij elke interactie bevragen is onpraktisch en vergroot de blootstelling.
+
+Persoonsgegevens zijn de data die wij het minst willen opbouwen. Een onbegrensde cache wordt stil een
+schaduwregister, met een onbeheerde bewaarverplichting als gevolg.
+
+## Besluit
+
+Een **begrensde cache** staat achter een Cache Port, beheerd door een Cache Manager. Vier grenzen
+gelden.
+
+| Grens | Wat die betekent |
+|---|---|
+| **Tijd** | Een TTL die aan het doel hangt |
+| **Omvang** | Alleen de werkset van een actieve zaak |
+| **Gezag** | Antwoordt nooit wat de bron niet zou antwoorden; geen systeem van registratie |
+| **Adresseerbaarheid** | Gesleuteld op subject, zodat verwijderen op verzoek kan |
+
+Purge-triggers: het verstrijken van de TTL, het sluiten van de zaak, en een verwijderingsverzoek.
+
+## Gevolgen
+
+**Positief:** de prestaties van een lokale kopie, zonder een onbevoegd register te worden. Bewaartermijn
+en het recht op verwijdering zijn echte operaties, geen hoop. Dit is consistent met zowel
+AVG-dataminimalisatie als FDS-data-bij-de-bron.
+
+**Negatief en kosten:** de mapping van doel naar TTL is een beleidsbesluit, samen met de FG en de
+autorisatievoorwaarden, en geen engineeringconstante. Die is dus makkelijk fout te krijgen. Daarnaast
+komt de complexiteit van cache-invalidatie erbij.
+
+**Vervolgwerk:** definieer het beleid voor doel naar TTL met de FG. Maak een toestandsdiagram voor de
+levensloop van een cache-entry. Documenteer de aanvaardbare veroudering per register.
+
+## Overwogen alternatieven
+
+- **Geen cache; altijd de bron bevragen** — afgewezen: onpraktische latency en belasting, en meer
+  blootstelling per aanroep.
+- **Een onbegrensde of algemene cache** — afgewezen: die wordt een schaduwregister, precies de
+  faalvorm waar de AVG en het FDS beide tegen duwen.
@@ -0,0 +1,42 @@
+# ADR-0005: Verwerkingenlog via event-emissie, in lijn met LDV
+
+- **Status:** accepted
+- **Datum:** 2026-06-13
+- **Deciders:** Lab Circle, FG (geconsulteerd)
+- **Vervangt / vervangen door:** —
+
+## Context
+
+AVG art. 30 vereist een register van verwerkingsactiviteiten. De FDS-bouwsteen Logboek
+Dataverwerkingen (LDV) wijst naar een gestandaardiseerd verwerkingslog dat de burger kan bevragen.
+
+Database-CDC met Debezium legt *datawijzigingen* vast, en niet *verwerkingsgebeurtenissen met
+doelbinding*. Het is dus geen verwerkingenlog.
+
+## Besluit
+
+Elke registeradapter stuurt een **verwerkingsactiviteit-event** naar een eigen Redpanda-topic, via een
+Verwerking Port en een LDV Emitter. Het event bevat: subjectcategorie, register, velden, doel en
+doelbinding, grondslag, bevragende rol, en tijdstempel. **Nooit de opgehaalde waarden.**
+
+Een projectie maakt het log bevraagbaar. De emissie is asynchroon, maar niet over te slaan: de adapter
+die de Register Port vervult, is dezelfde code die het event uitstuurt.
+
+## Gevolgen
+
+**Positief:** het spoor voor art. 30 en LDV ontstaat als neveneffect van de bevraging, dus het kan niet
+uit de pas lopen met de werkelijkheid. Het is af te stemmen tegen de tweezijdige logs van FSC
+(ADR-0002). Het is onderscheidend in een tender.
+
+**Negatief en kosten:** een topic en een projectie om te exploiteren. Het ontsluiten van het log naar
+de burger valt buiten de huidige scope; wij produceren het log. Het eventschema vraagt governance.
+
+**Vervolgwerk:** definieer het schema van het verwerkingsevent. Bouw de bevraagbare projectie. Sluit
+aan op de LDV-standaard zodra die volwassen wordt; dit is een upstream-kandidaat.
+
+## Overwogen alternatieven
+
+- **Debezium-CDC hergebruiken als log** — afgewezen: dat legt datawijzigingen vast, en geen verwerking
+  met doelbinding. Verkeerde semantiek.
+- **Synchroon loggen in het aanroeppad** — afgewezen: dat koppelt de latency van de bevraging aan het
+  log. Asynchroon maar niet over te slaan geeft zowel snelheid als garantie.
@@ -0,0 +1,68 @@
+# ADR-0006: Modulegrens en hergebruikstrategie voor de governed-access spine
+
+- **Status:** accepted
+- **Datum:** 2026-06-13
+- **Deciders:** Lab Circle (Lead Link, Build, Upstream Liaison)
+- **Vervangt / vervangen door:** —
+
+## Context
+
+De compliance-spine uit slice 1 bestaat uit de PDP-controle (ADR-0003), gegoverneerd uitgaand verkeer
+via FSC (ADR-0002), emissie van het verwerkingenlog (ADR-0005), en de begrensde cache (ADR-0004),
+allemaal achter ports (ADR-0001). Die spine is mogelijk breder herbruikbaar dan alleen in de
+referentie-applicatie.
+
+Er spelen twee hergebruikvragen: welke verpakkingsvorm kiezen wij, en hoe verhoudt de spine zich tot
+andere omgevingen zoals het OpenMetadata-datagovernanceproject?
+
+Twee verduidelijkingen bepalen het besluit.
+
+1. **OpenMetadata is geen afnemer.** In het datagovernanceproject is het de catalogus- en
+   lineage-laag over (synthetische) data. Het bevraagt geen BRP of NHR. FSC of de begrensde cache
+   daarin inbouwen zou zinloos zijn. De juiste aansluiting is **integratie van de output van de
+   spine**, en niet het inbouwen van de spine.
+2. **FSC en de begrensde cache zijn zaken die alleen een afnemer aangaan.** "Maak het herbruikbaar"
+   mag deze niet uitsmeren over componenten die geen registerdata bevragen.
+
+Nu al een taalonafhankelijke gateway bouwen — vóórdat er een tweede, niet-.NET afnemer bestaat — zou
+de valkuil van speculatieve architectuur herhalen, die wij voor de capability-laag al hebben
+afgewezen.
+
+## Besluit
+
+Wij nemen een **vraaggestuurde reeks van vier stappen** aan. Elke stap hangt af van echte behoefte, en
+niet van verwachte behoefte.
+
+| Stap | Wat | Wanneer |
+|---|---|---|
+| 1 | **In-process bewijzen.** Bouw de spine als gewone componenten achter ports, binnen de .NET register-applicatie. Nog geen extractie. Doel: de compliance-invarianten één keer echt valideren. | Slice 1 |
+| 2 | **Extraheren als .NET-module.** Zodra een tweede .NET-afnemer in zicht is, haal de spine eruit als een geversioneerde .NET-library of SDK. Dit is de ACL-template-extractie die het charter al plant. Herbruikbaar voor .NET-afnemers, en dat is genoeg voor register-reference en zijn broertjes. | Slice 3 |
+| 3 | **De feed LDV naar OpenMetadata aansluiten.** Route verwerkingsevents uit de LDV-emitter naar OpenMetadata als access- en usage-metadata bij het geclassificeerde asset: wie las welk persoonsgegevensveld, met welk doel, hoe vaak. Optioneel laten classificatietags uit OpenMetadata terugstromen om veldminimalisatie in de ACL aan te sturen. Dit is de concrete brug tussen beide anchor-projecten: integratie, geen inbouw. | Na stap 2 |
+| 4 | **Alleen op verzoek een taalonafhankelijke gateway bouwen.** Heeft een echte niet-.NET afnemer gegoverneerde registertoegang nodig, verpak de spine dan als zelfstandige sidecar of proxy met een dunne lokale API, met PDP, FSC-egress en LDV erachter. Niet eerder. | Op verzoek |
+
+## Gevolgen
+
+**Positief:** eigen software blijft minimaal. Hergebruik volgt op validatie in plaats van eraan vooraf
+te gaan. Beide anchor-projecten krijgen een concreet, benoemd integratiepunt (stap 3). Zaken die
+alleen een afnemer aangaan, blijven ingesloten.
+
+**Negatief en kosten:** de .NET-module uit stap 2 dient geen niet-.NET afnemers. Dat aanvaarden wij,
+omdat stap 4 dat geval dekt zodra het echt is. Stap 3 vraagt een afgesproken schema voor het
+verwerkingsevent, stabiel genoeg voor OpenMetadata om te consumeren.
+
+**Vervolgwerk:**
+
+1. Neem stap 3 als expliciet integratiepunt op in beide projectpagina's in het Innovation Lab-repo:
+   `projects/open-register-fd/README.md` en `projects/openmetadata/README.md`.
+2. Herzie de trigger van stap 4 bij elke portfolio-review. Bouw niet vooruit.
+3. Regel governance op het schema van het verwerkingsevent; dat is een gedeelde afhankelijkheid van
+   stap 1 en stap 3.
+
+## Overwogen alternatieven
+
+- **De taalonafhankelijke gateway vooraf bouwen** — afgewezen: speculatieve architectuur voordat er een
+  tweede afnemer bestaat. De latency en de operationele kosten zijn niet te rechtvaardigen.
+- **De spine in OpenMetadata inbouwen** — afgewezen: OpenMetadata is geen afnemer. Dit is een
+  categoriefout.
+- **De spine permanent in-process houden, zonder extractie** — afgewezen: dat geeft het hergebruik
+  tussen projecten en applicaties weg, en dat is een kerndoel van de Open Register-inzet.
@@ -0,0 +1,27 @@
+# ADR-NNNN: <titel>
+
+- **Status:** proposed
+- **Datum:** JJJJ-MM-DD
+- **Deciders:** <rollen>
+- **Vervangt / vervangen door:** —
+
+## Context
+
+<De krachten die spelen: het probleem, de beperkingen, de FDS- en AVG-drijfveren. Waarom er nu een
+besluit nodig is.>
+
+## Besluit
+
+<De keuze, eenvoudig gesteld.>
+
+## Gevolgen
+
+**Positief:** <wat dit oplevert>
+
+**Negatief en kosten:** <wat het kost, en wat wij aanvaarden>
+
+**Vervolgwerk:** <welk werk dit oproept>
+
+## Overwogen alternatieven
+
+<De afgewezen opties, en waarom.>