eho
321ee50dcb
## What & why Brings the engineer-facing FDS documentation next to the code it describes. Imported from `projects/open-register-fd/` in `Respellion/innovation-lab` and translated to Dutch: **six ADRs**, the ADR index and template, the **L3 component view**, and the **slice-1 proposal**. The architecture blueprint, the FDS gap analysis and the two privacy views stay in the lab repo — the OKRs cite them and they feed tender responses. Each side names the split in a "Wat ligt waar" table, so nothing is documented twice. Closes #159 ### Why `docs/architecture/fds/` and not `docs/architecture/` This repo's own ADR series now runs `adr-0001-loose-coupling` … `adr-0010-bff-oidc`. The imported set is numbered 0001–0006, so a flat import would collide across the whole imported range. The subfolder preserves the imported numbering, and with it roughly thirty `ADR-000N` cross-references inside the imported text that would otherwise all need rewriting. In the MkDocs sidebar the imported six appear as **FDS ADR-000N** so they are not confused with this repo's series. `docs/architecture/fds/README.md` explains the two series. ### Mermaid support was missing `pymdownx.superfences` had no `custom_fences`, so the imported diagrams would have published to Gitea Pages as raw code blocks. This PR adds the mermaid custom fence, the nav group, and one link under *Where to go* in the docs index. ## Definition of Done - [x] Linked Gitea issue (above). - [ ] Failing test committed before the implementation. — n/a, documentation only. - [ ] Implementation makes the test pass. — n/a, documentation only. - [x] Conventional Commits referencing the issue (`refs #159`). - [x] Rebased on current `main`; no conflicts. - [ ] CI green — n/a for content; the docs verification is below. - [ ] `docker compose up` reaches green health checks. — n/a, no runtime change. - [x] Docs updated if behaviour, contracts, or operations changed. - [x] ADR added in `docs/architecture/` if a non-obvious decision was made. — six imported, plus the numbering decision recorded in the folder README. - [ ] Demo note in `docs/demo-script.md`. — n/a, nothing user-visible. ## Verification run - `mkdocs build` — clean. No missing-nav warning for any `architecture/fds/` entry. The two remaining warnings are pre-existing on `main` and untouched here: the set of pages absent from `nav`, and a broken link in `runbooks/ci.md` to `services/acl/stryker-config.json`. - Mermaid renders as a diagram, not a code block: `site/architecture/fds/c4-component-view/index.html` contains `class="mermaid"`. - All relative markdown links in the repo resolve. ## Notes for reviewers - **Language.** The imported documents are Dutch; this repo's own documents remain English. Deliberate, not an oversight — the lab repo standardised on Dutch and these pages moved with it. Translating the rest is a separate decision. - **Ownership.** This repo sits in the `eho/` namespace while it now holds the canonical FDS architecture decisions that tender answers point at. Worth deciding whether it should move to `Respellion/`. - **Scope drift, not fixed here.** The imported text is faithful to its source, so the slice-1 proposal and the ADRs assume NHR/KVK for slice 1, while the lab-side blueprint still uses BAG as its example register. The lab-side documents carry a banner about this; Blueprint v2 (slice 5) is where the diagrams get corrected. - **Companion PR:** `Respellion/innovation-lab` #34 holds the lab-side half of this split.Reviewed-on: #160
5.1 KiB
POC-voorstel — slice 1: walking skeleton (één register, gegoverneerde bevraging)
Klaar om in een
poc-voorstel-issue te plakken, met de labelsbuildenpoc. 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.
- Afgewerkte interface of NL Design System-schermen, verder dan een dev-harness.
- BRP en paden met veel persoonsgegevens. Die gaan naar slice 2, met een door de FG beoordeelde policy.
- UBO-data. Het regime van beperkte toegankelijkheid valt buiten deze slice.
- De terugmelding-workflow (latere slice), DCAT-export, en Superset-dashboards.
- Echte register-endpoints. Alleen sandbox en stubs.
Definition of Done
- Een bevraging op KVK-nummer geeft een domein-
Organisatieterug 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.