atomic-design-poc/docs/reference/architecture/0004-stamdata-as-code.md

ADR-0004 — Stamdata as code (config-as-code, not a production database)

Status: Accepted · Date: 2026-07-20

Context

The business needs to control certain inputs that change over time — the clearest example being which professions link to which diplomas (geneeskunde → Arts, …), but also tunable thresholds, policy-question text, document-category definitions, and some letter copy. Two hard constraints:

1. No managing this through a production database. A live admin surface writing DB rows means a bad value ships silently and is discovered in production.
2. Issues must be caught at compile time. A change should be typed, reviewed, and versioned before it can affect anyone.

The codebase already leans this way but had never named it as a pattern, and one key table was neither isolated nor validated:

• All reference data and thresholds are compiled-in C# constants, served through screen-shaped BFF-lite endpoints; the frontend renders decisions and holds no reference data (ADR-0001).
• User-facing UI copy is already $localize (src/locale/*.xlf) — git-tracked, and a second locale is a translation file, not a code change. That is already the compile-time model for text.
• The profession↔diploma map lived as a private Dictionary inside DiplomaRules, mixed in with the rules that consume it, with no cross-reference check: a diploma whose program wasn't in the map silently rendered "Onbekend".

Decision

Treat business-tunable reference data as stamdata-as-code: typed, checked-in configuration, changed through the normal git → PR → build → deploy pipeline. Never a production database, never runtime-editable.

1. One home, typed. Business-editable reference data lives in the BigRegister.Stamdata namespace (backend/src/BigRegister.Api/Stamdata/), one file per concern. A table lives either as plain typed C# data (records / dictionaries) or as a typed JSON data-file deserialized into a record (professions.json → ProfessionMapping, loaded via StamdataFile). Both are checked-in config-as-code, gated the same way; the data-file trades the compiler's value check (gate #1 sees only the shape, not a wrong beroep) for hand-editing ergonomics and the low-code editor below — the value gate becomes StamdataValidationTests. Separate the data (what the business tunes) from the rules (dev-owned logic that consumes it): the profession table is Stamdata.Professions; the rule "an English diploma needs a B2 question" stays in DiplomaRules. Tables may carry valid-time (geldigVan/geldigTot, half-open [van, tot)); StamdataCatalog + StamdataTable.Of<T> describe every table generically (columns reflected from the record) so one endpoint pair and one grid editor serve all of them.
2. Served unchanged. The existing BFF-lite endpoints keep serving this data (/duo/diplomas, /intake/policy, /uploads/categories, …). No frontend change — the FE still renders decisions.
3. Two gates. The C# compiler catches shape and type mistakes. A build-time StamdataValidationTests catches the referential integrity the compiler can't — every seeded diploma program resolves to a real profession, no blank keys/values, thresholds in range. CI runs it, so a bad edit fails the build and never merges.
4. Business control = config-as-code (GitOps). The business owns the content of these files; a change is a reviewed edit, not a live DB write. A future low-code editor could commit a PR on their behalf without changing this model (the compile-time gate stays).

Where each kind of business-controllable thing lives

Kind	Home	Gate
Reference tables + tunable numbers (professions↔diplomas, thresholds, policy questions, document categories)	Stamdata/ typed C# or typed JSON data-file (professions.json), optionally valid-timed	compiler (shape; + values when C#) + StamdataValidationTests (values, references, validity windows)
User-facing UI copy	$localize → src/locale/*.xlf	build (i18nMissingTranslation: error)
Letter / brief passage content	config-as-code in the backend (seed content), not the DB	compiler + endpoint tests

The deliberate exception: org-templates

Per-organization letterhead (return address, footer, signature, margins) is runtime-editable in SQLite, via the org-template admin editor (WP-23/26). That is intentional and does not contradict this ADR: it is operational configuration owned by an admin persona, versioned with publish/rollback inside the app, and specific to one sub-organization's identity — not the shared business rules a wrong value would break for everyone. Stamdata (the rules and reference tables the whole register runs on) stays code.

Consequences

• + Every change is typed, reviewed, versioned, and rollback-able through git; zero production-DB risk; a dangling reference fails the build with a clear message instead of reaching users.
• − A change needs the PR pipeline — not instant, and a non-developer may need dev assistance to edit C# (mitigated later by a low-code editor that emits a PR, or by a data-file format if hand-editing ergonomics ever outweigh maximal compile-time safety).
• Shipped with this ADR: the profession↔diploma map (Stamdata/Professions.cs) and the policy-question wording (Stamdata/PolicyQuestions.cs) extracted from DiplomaRules, which now consumes both (behaviour unchanged), guarded by StamdataValidationTests. Document-category definitions follow the same pattern as the obvious next step; not moved yet.
• Shipped as a follow-on (WP-29): the "future low-code editor" and "data-file format" this ADR floated are now real. professions moved to professions.json (typed, valid-timed) and the generic StamdataCatalog/StamdataTable/StamdataFile model plus read-only, admin-gated GET /stamdata endpoints back an Angular beheer/stamdata editor. It is not a runtime write path: the admin edits a grid and downloads the edited JSON to commit as a reviewed PR — the compile/validation gate stays the authority, so this ADR's core decision is unchanged.