docs(architecture): import the FDS architecture decisions (refs #159)
CI / lint (pull_request) Successful in 1m26s
CI / build (pull_request) Successful in 1m13s
CI / unit (pull_request) Successful in 1m39s
CI / frontend (pull_request) Successful in 3m32s
CI / mutation (pull_request) Successful in 6m33s
CI / verify-stack (pull_request) Successful in 8m16s

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>
This commit is contained in:
eho
2026-09-03 11:29:07 +02:00
co-authored by Claude Opus 5
parent 94720f0fcb
commit 700399992a
12 changed files with 614 additions and 1 deletions
+103
View File
@@ -0,0 +1,103 @@
# POC-voorstel — slice 1: walking skeleton (één register, gegoverneerde bevraging)
> Klaar om in een `poc-voorstel`-issue te plakken, met de labels `build` en `poc`. Dit is het bouwbare
> eerste increment dat de architectuurdocumenten beschrijven. Het bewijst met opzet de
> *compliance-spine* end-to-end op de dunst mogelijke functionaliteit.
## Probleem en strategische vraag
Kunnen wij een registerbevraging demonstreren die *structureel* gegoverneerd is — onmogelijk uit te
voeren zonder gehandhaafde grondslag en een automatische regel in het verwerkingenlog — op onze
soevereine stack?
Dit is de geloofwaardigheidstoets achter de hele Open Register-inzet (slice 1 van het charter) en
achter de FDS gap-analyse.
## Hypothese
Wij verwachten dat het doorverbinden van één registerbevraging door de volledige capability-spine —
Register Port → ACL-adapter → PDP-controle → FSC-aanroep → LDV-emissie → begrensde cache — de claim
"compliance is structureel" bewijst.
Wij weten dat wij het goed hebben als een geautomatiseerde test aantoont dat een bevraging **niet** kan
voltooien als de PDP weigert, en **altijd** een LDV-event oplevert als de PDP toestaat.
## Scope ter grootte van één blok
**Wel in scope**
| Onderdeel | Wat |
|---|---|
| Register | **NHR/KVK**, basisgegevens over onderneming en bestuurder. Gekozen boven BRP; zie de slotnotitie. |
| Use case | Geef bij een KVK-nummer de geregistreerde organisatie terug aan het domein, voor één verklaard doel. |
| Ports | De vijf ports als interface. Concrete adapters: NHR-ACL, PDP-client (OPA), FSC-client met sandbox- of test-outway, LDV-emitter (Redpanda-topic), en cache manager (PostgreSQL met TTL). |
| Policy | OPA draait met één handgeschreven voorbeeldpolicy in Gitea: één allow-regel en één deny-geval. |
| Log | Verwerkingsevent-schema v0 plus een minimale bevraagbare projectie; een tabelweergave is genoeg. |
| Tests | Tests die de twee compliance-invarianten vastleggen: deny blokkeert, allow logt. |
**Niet in scope** — even belangrijk om op te schrijven.
1. Afgewerkte interface of NL Design System-schermen, verder dan een dev-harness.
2. BRP en paden met veel persoonsgegevens. Die gaan naar slice 2, met een door de FG beoordeelde
policy.
3. UBO-data. Het regime van beperkte toegankelijkheid valt buiten deze slice.
4. De terugmelding-workflow (latere slice), DCAT-export, en Superset-dashboards.
5. Echte register-endpoints. Alleen sandbox en stubs.
## Definition of Done
- [ ] Een bevraging op KVK-nummer geeft een domein-`Organisatie` terug via de NHR-ACL-adapter, zonder
registervocabulaire in het domein (ADR-0001).
- [ ] De aanroep loopt via de FSC-client naar een sandbox-outway, en niet via een ruwe HTTP-client
(ADR-0002).
- [ ] Er vindt geen bevraging plaats tenzij de PDP allow teruggeeft voor de combinatie rol, doel en
grondslag (ADR-0003).
- [ ] Elke toegestane bevraging stuurt precies één verwerkingsevent naar Redpanda, bevraagbaar in de
projectie, zonder opgehaalde waarden (ADR-0005).
- [ ] Cache-entries dragen een TTL en een subjectsleutel; een purge-aanroep verwijdert ze (ADR-0004).
- [ ] **De tests op de compliance-invarianten slagen in CI:** (a) PDP-deny betekent geen FSC-aanroep;
(b) PDP-allow betekent precies één LDV-event; (c) te ruim gevraagde velden bereiken het domein
nooit.
- [ ] Het geheel draait lokaal uit een gedocumenteerd `compose`- of k3s-manifest met stubs, zonder
echte registertoegang.
- [ ] ADR-0001 tot en met ADR-0005 zijn vanuit de code gelinkt. Eén nieuwe ADR als er in slice 1 een
besluit ontstaat.
## Acceptatiedemo (bewijs voor de week-3-toets)
Live: een geslaagde bevraging plus de bijbehorende LDV-regel. Zet daarna de policy op deny en toon
dezelfde bevraging geweigerd, zonder registeraanroep en zonder data.
Dat contrast *is* de demo.
## Ontvangende Delivery Circle (voorlopig)
De register-reference Delivery Circle. De Handoff-ontvanger krijgt bij de kickoff een naam.
Waarschijnlijke adoptie: de capability-spine wordt het herbruikbare substraat voor de
register-reference-applicatie.
## Upstream-kandidaten
| Project | Wat wij kunnen bijdragen |
|---|---|
| fsc-nlx | Ergonomie van de sandbox en testomgeving, plus documentatie |
| OPA | Policy-patronen voor het modelleren van Nederlandse grondslagen |
| OpenMetadata | Later een DCAT-AP-NL exporter; dit verbindt het OpenMetadata-project |
## AVG- en soevereiniteitsoverwegingen
Alleen NHR-basisgegevens, over onderneming en bestuurder, en in slice 1 **gestubd**. Er worden geen
echte persoonsgegevens verwerkt.
Een FG-review is een voorwaarde voor slice 2, met echte data en BRP. Alle componenten draaien
zelfgehost op De Werf; OPA-policies en BPMN staan in Gitea.
## Slotnotitie: waarom NHR vóór BRP voor het skeleton
Beide registers bevatten persoonsgegevens, dus geen van beide is "gratis". NHR-basisgegevens over
onderneming en bestuurder zijn echter minder gevoelig dan BRP-gegevens over inwoners, en er is een
duidelijker verhaal rond een publieke sandbox.
Zo bewijst slice 1 het *mechanisme*, voordat slice 2 BRP oppakt onder een door de FG beoordeelde
policy. UBO-data blijft buiten scope tot het toegangsregime is gemodelleerd.