Decision Records

Declare the architecture decision records behind your configuration — why the app is the way it is, in Nygard's four parts, versioned with the config.

An operator who inherits a running app can read every property of it and still not know why any of them is the way it is. Why Postgres and not the SQLite default? Why is the margin column hidden from the workshop? A config file answers what, and a diff answers what changed — neither answers what it was in aid of.

So the reasoning moves somewhere the config does not travel to: a wiki, a shared page, a thread, a person who has left. It drifts within a release or two, and the app outlives it.

The decisions array puts the records beside the configuration they decided, in the same file, under the same review, shipped in the same binary:

decisions:
  - id: ADR-002
    title: SQLite on the workshop PC
    status: superseded
    date: '2025-11-04'
    deciders:
      - Thomas
    supersededBy: ADR-007
    touches:
      - engine › DATABASE_URL
    context: Two people use the app and it runs on the machine in the workshop.
    decision: No DATABASE_URL. The app keeps its SQLite file beside the binary.
    consequences: Backups are whoever remembers to copy the file. No second service to run.
  - id: ADR-007
    title: Postgres for the shared instance
    status: accepted
    date: '2026-06-01'
    deciders:
      - Léa Fontaine
      - Thomas
    supersedes: ADR-002
    touches:
      - engine › DATABASE_URL
      - tables › quotes
    context: Fourteen accounts write to the app, two agents read it, and the nightly export locks the file for a minute.
    decision: DATABASE_URL points at a managed Postgres in eu-west-3. The binary is unchanged; the migrations run at boot as before.
    consequences: Backups are the provider's. The workshop PC no longer hosts anything.

Record properties

deciders

touches

context, decision and consequences are the three prose parts of a classic Nygard ADR. The shape is deliberately the one every ADR tool already uses, so a team arriving with a docs/adr/ folder is transcribing rather than translating.

The whole array is optional. An app that declares no decisions is not an error case anywhere — it simply has an empty register.

Status

status is what makes a register out of a pile of records:

A superseded decision is still a decision. Deleting it deletes the reason the current one exists, which is why the register keeps it rather than pruning it.

What touches is

touches names what a decision was about, as the author wrote it: engine › DATABASE_URL, tables › quotes, forms › quote-request, or a bare auth. It is free display text, and nothing dereferences it.

It is deliberately never resolved against the configuration, and that is the register's central design decision rather than an omission. A decision necessarily outlives what it decided: the record above documents the SQLite era of an app that now runs Postgres, and a superseded record names configuration that is gone by definition. A cross-reference rule here would refuse a boot because the register was honest about its own history, and would teach you to delete the record instead of keeping it.

So a touches entry naming nothing that exists in your config boots, and round-trips verbatim. The › is a separator the reading surface renders, not a path the schema splits on — use whatever vocabulary your team already uses.

Supersession

supersedes and supersededBy are both authored. Neither is derived from the other, because the config is a file a human reads and a derived field would put a row on the reader's screen that is in no file.

The price of authoring both ends is that they can disagree — and a one-sided link renders a lineage chip on one screen and a dash on the other. So the pair is cross-checked when the config is decoded, and these six shapes are refused at startup rather than rendered wrongly:

The converse of the fifth row is allowed and left alone: status: superseded with no supersededBy is the honest record of a decision that was abandoned, which is not the same thing as one that was replaced.

Why the date is pinned

id accepts any non-empty string, and date does not. That is not an inconsistency.

The only property the register needs from an id is that a lineage link can resolve it, so pinning a pattern such as ADR-\d{3} would refuse RFC-12, ARCH-001 and D-7 — conventions teams actually use — for a house style.

A date has a reader. A register is ordered newest-first by comparing the raw strings, which is chronological for ISO-8601 calendar days and silently wrong for everything else: 01/06/2026 sorts beside 01/02/2025, the page still renders, still answers 200, and lies about which decision came last. So date must be YYYY-MM-DD, and anything else is refused at startup.

It is a calendar day rather than a timestamp, deliberately: an instant round-trips through a timezone that can move the day.

Nothing edits a decision

The register is read-only wherever it is displayed. A decision is authored in the config, reviewed as a diff, and shipped with the app — which is the whole point of putting it there. An operator console that let someone rewrite the reasoning would reintroduce exactly the drift the register exists to end.

Behaviour

Embed the dashboard config and auto-mount it at /_admin, independent of and unbreakable by the operator's config

• (assertion) An admin who opens /_admin on a booted app gets a rendered dashboard surface (200 + shell content) sourced from the embedded system config, not from the operator's own config
• (assertion) /_admin renders identically whether the operator's config defines pages at / or not — the mount is independent of the operator's config (a minimal app and a page-rich app both expose /_admin)
• (assertion) The embedded dashboard surfaces are a distinct, platform-owned artifact — they are NOT exposed in the operator API; the operator's config never contains the dashboard config's pages/components
• (assertion) admin: false removes the console: /_admin is 404 for a signed-in admin, not just for anonymous, while the operator's own page still serves
• (assertion) SOVRIUM_ADMIN=off wins over admin: true — boot stays green and /_admin is 404 for a signed-in admin, while the operator's own page still serves
• (assertion) An operator page inside the /_admin subtree is a named boot failure, never a silently shadowed route — startup is refused with a message naming both the mount and the offending page
• (assertion) The /_admin mount path does not leak into the sitemap or the operator OpenAPI document, while the operator's own page and table routes stay listed in them
• (assertion) Every navigation action the console authors resolves inside the mount base — the operator menu's "My account" row points at /_admin/profile and lands on the console's own profile page, whose h1 names the signed-in operator, while its external GitHub rows stay absolute and the operator's own /profile still 404s
• (workflow) An admin signs in, opens /_admin on a minimal app and sees the rendered shell sourced from the embedded config, confirms it renders independent of the operator config and stays out of the public surface, then removes it by config and by environment, and is refused a colliding page

Read the decisions behind the app I operate

• An admin reads every declared decision, in declared order, with all four Nygard parts
• The response carries flat total / accepted / proposed / superseded counts
• An app declaring no decisions answers 200 with an empty list and four zero counts
• A member and an anonymous caller both get 404 — never 401 or 403
• deciders round-trips as an array of names, not a joined string
• A supersededBy naming no declared decision is refused at boot
• A one-sided lineage link is refused at boot, naming both records
• Two decisions sharing an id are refused at boot
• A date that is not an ISO calendar day is refused at boot
• A touches entry naming no config node BOOTS and round-trips verbatim