eho/register-referentie
1
0
Fork 0
Code Issues 10 Pull Requests 1 Actions Packages Projects Releases 1 Wiki Activity

docs(architecture): import the FDS architecture decisions from the lab repo (closes #159) #160

Merged
eho merged 1 commits from docs/159-fds-architectuur into main 2026-09-03 12:35:02 +00:00
Conversation 0 Commits 1 Files Changed 12
+614 -1
eho commented 2026-09-03 09:28:00 +00:00
Owner
Copy Link
Copy Source

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

  • Linked Gitea issue (above).
  • Failing test committed before the implementation. — n/a, documentation only.
  • Implementation makes the test pass. — n/a, documentation only.
  • Conventional Commits referencing the issue (refs #159).
  • 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.
  • Docs updated if behaviour, contracts, or operations changed.
  • 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.
## 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.
eho added 1 commit 2026-09-03 09:29:26 +00:00
docs(architecture): import the FDS architecture decisions (refs #159)
CI / lint (pull_request) Successful in 1m26s
Details
CI / build (pull_request) Successful in 1m13s
Details
CI / unit (pull_request) Successful in 1m39s
Details
CI / frontend (pull_request) Successful in 3m32s
Details
CI / mutation (pull_request) Successful in 6m33s
Details
CI / verify-stack (pull_request) Successful in 8m16s
Details
700399992a 
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>
eho force-pushed docs/159-fds-architectuur from 334cec0157 to 700399992a 2026-09-03 09:29:26 +00:00 Compare
eho scheduled this pull request to auto merge when all checks succeed 2026-09-03 10:45:46 +00:00
eho scheduled this pull request to auto merge when all checks succeed 2026-09-03 12:26:26 +00:00
eho merged commit 321ee50dcb into main 2026-09-03 12:35:02 +00:00
eho deleted branch docs/159-fds-architectuur 2026-09-03 12:35:02 +00:00
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
Clear labels
area:acl
area:bff
area:docs
area:domain
area:event-subscriber
area:infra
area:portal-behandel
area:portal-beheer
area:portal-openbaar
area:portal-self-service
area:projection
area:workflow
type:adr-proposal
type:bug
type:chore
type:slice
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
eho (Edwin van den Houdt)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: eho/register-referentie#160