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
69 lines
4.3 KiB
Markdown
69 lines
4.3 KiB
Markdown
# 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.
|