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
104 lines
5.1 KiB
Markdown
104 lines
5.1 KiB
Markdown
# 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.
|