docs(architecture): import the FDS architecture decisions from the lab repo (closes #159) (#160)
CI / build (push) Successful in 1m36s
CI / lint (push) Successful in 1m45s
CI / unit (push) Successful in 2m1s
CI / frontend (push) Successful in 3m30s
CI / mutation (push) Successful in 8m4s
CI / verify-stack (push) Successful in 9m25s

## 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
This commit was merged in pull request #160.
This commit is contained in:
eho
2026-09-03 12:35:01 +00:00
parent 94720f0fcb
commit 321ee50dcb
12 changed files with 614 additions and 1 deletions
@@ -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.