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 (apps/<app>/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 → apps/<app>/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: operational configuration

"Never runtime-editable" above is the rule for stamdata — the shared reference tables and business rules the whole register runs on. It is not a ban on all persisted configuration. Some configuration is operational rather than business-rule, and belongs to an admin persona at runtime.

This section states the test rather than a list, so the next surface can check itself instead of arguing by analogy. Runtime-editable persistence is permitted only when all four hold:

1. The catalog lives in code. What may be set — the keys, the schema, the defaults, the descriptions — is compiled in and reviewed through git. The store holds values, never the definition of what a value means.
2. An unknown or unlisted key fails closed. A row the code catalog does not know cannot invent a setting, enable a feature, or be written. A bad row is inert, not authoritative.
3. The value is operational. Per-organisation identity, or an on/off rollout switch — not a shared business rule whose wrong value breaks the register for everyone. This is the clause that keeps stamdata out.
4. Writes are admin-capability-gated and audited. The write path goes through an Authz capability gate, and the gate records the decision — allow as well as deny — in AuthzAuditStore.

Two surfaces pass this test today.

Surface	(1) catalog in code	(2) fails closed	(3) operational	(4) gated + audited
OrgTemplateStore (WP-23/26)	the OrgTemplateDto shape + OrgTemplateRules	unknown subOrgId → null → the endpoint 404s	one sub-organisation's letterhead	OrgAdmin → orgtemplate:edit
FeatureFlagStore (WP-47)	Domain/Features/FeatureFlags.Catalog	unknown key → Set returns false (404); IsEnabled → false	an on/off rollout switch	FlagsAdmin → flags:manage

Clause (4) became true for both only with RB-07, which moved AuditAuthz from each gate's deny branch into the gate itself so the allow path is recorded too. Before that, both surfaces were gated and not audited, and this ADR would have ratified a control the code did not implement.

Org-templates also carry publish/rollback versioning inside the app, which is stronger than the test requires but not part of it.

Stamdata itself — the rules and reference tables — fails clause (3) by construction and 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.