# Stamdata (config-as-code reference data) — how it's built & extended

Business-tunable reference data — the tables the business controls (profession↔diploma map,
policy-question text, thresholds) — is **typed, checked-in config changed via git → PR →
build**, not a runtime-editable database. For the _why_, see
[ADR-0004 — Stamdata as code](architecture/0004-stamdata-as-code.md); this page is _how the
code is laid out and how to add a table without coupling_. Built in WP-29, hardened in WP-48.

Tables today: `professions` (opleiding-program → beroep), `beroepen` (the BIG professions master
list), `opleidingen` (temporal; `beroep` → `beroepen.code`) and `specialismen` (`beroep` →
`beroepen.code`). The last two are **stamdata → stamdata** references — one table keyed on by two
others — enforced by the CI gate below.

## The one rule that shapes everything: no runtime write path

The catalog is the source of truth and lives in code. The admin editor **downloads** an
edited `{table}.json` for a human to commit — it never PUTs. The authority that a change is
valid is the **CI gate**, not the server. This is what keeps a bad edit out of prod instead
of out of the database.

## Layered pipeline

Backend (`backend/src/BigRegister.Api/Stamdata/`):

- `StamdataCatalog.cs` — the registry. Adding a table is **one line**:
  `StamdataTable.Of<ProfessionMapping>("professions", …)`.
- `StamdataTable.cs` — generic table model: columns are _reflected_ from the typed record
  (first property = key; temporal iff it has `geldigVan`+`geldigTot`). Holds `Validate()`
  (referential integrity) and `RowsOn(date)`.
- `StamdataFile.cs` — reads the JSON as an **embedded resource** (identical read from API
  and test assembly). No write method exists.
- Endpoints in `Program.cs`: `GET /stamdata` and `GET /stamdata/{table}?peildatum=` —
  **reads only**, both behind the `StamdataAdmin` gate.

Frontend (`src/app/beheer/`, the `beheer` context):

- `domain/stamdata.ts` (pure model + `activeOn`/`rowErrors`/`toJson`),
  `domain/stamdata-editor.machine.ts` (Elm-style union — **no save Msg by design**).
- `contracts/stamdata.dto.ts` → `infrastructure/stamdata.adapter.ts` (`list()`/`load()`
  with a `parseStamdataTable` trust boundary; **no write method**).
- `application/stamdata.store.ts` — root singleton; derives `dirty`/`counts`/`errors`;
  `download()` serializes the edited table to a blob to commit.
- `ui/stamdata.page.ts` (thin container) + `ui/stamdata-table-editor/` (the generic grid).

## How to add a table (zero UI code)

1. Add a typed record + its `professions.json`-style embedded JSON in `Stamdata/`.
2. Register it with one line in `StamdataCatalog.cs`.
3. If it references another table, add a `StamdataRef` to the CI gate (below).

That's it — the editor grid renders from the reflected column schema, so **no per-table
component**. This is the payoff of the schema-driven design.

## The CI gate is the authority

`backend/tests/BigRegister.Tests/StamdataValidationTests.cs`. `Every_catalog_table_is_valid`
covers every registered table generically; the `StamdataRef` list catches dangling
references — both seed → stamdata (`Diploma.Opleiding → professions.program`) and
stamdata → stamdata (`Opleiding.beroep → beroepen.code`, `Specialisme.beroep →
beroepen.code`). A bad edit, an orphaning delete, or a premature expire **fails the PR
build** — never prod. Adding a cross-table FK is one `StamdataRef` entry: the referencing
keys + a resolver against the target table's (valid-today) keys.

## Coupling

Low, and deliberately so. The page is a thin container binding store signals to the grid
organism and mapping the organism's outputs back to store commands
(`(cellEdited)="store.editCell(…)"`); the organism owns no state (pure input/output).
Because the editor is schema-driven, a new table adds **no** UI coupling. The only
editor-side niceties (WP-48) are fast-feedback nudges — `onExpire()` reuses the `CellEdited`
output to set `geldigTot`; the CI gate stays authoritative.

## See also

- [ADR-0004 — Stamdata as code](architecture/0004-stamdata-as-code.md) — the decision + the org-template exception.
- [WP-29](../project/backlog/WP-29-stamdata-beheer-editor.md) (editor), [WP-48](../project/backlog/WP-48-stamdata-deletion-protection.md) (deletion protection).
- `backend/src/BigRegister.Api/Stamdata/StamdataCatalog.cs` — register a table here.
- `backend/tests/BigRegister.Tests/StamdataValidationTests.cs` — the authoritative gate.
- `src/app/beheer/ui/stamdata-table-editor/` — the generic, schema-driven grid.
- [Roles & access](roles-and-access.md) — the `stamdata:edit` capability + admin gating.