0001. Record architecture decisions¶

Date: 2026-07-14 Status: Accepted

Context¶

Conflux's documentation mixed significant architecture decisions into narrative "Explanation" pages (see explanation/tenant-model.md before this restructure), each wrapped in an ad-hoc "Decision: ... / Why / Open" admonition. This made decisions hard to find, hard to link to individually, and impossible to mark as superseded without rewriting the prose around them.

Decision¶

Conflux records significant architecture decisions as Architecture Decision Records (ADRs) in docs/docs/adr/, one file per decision (or per tightly-coupled group of decisions), numbered sequentially with a 4-digit zero-padded prefix and a present-tense-imperative kebab-case title.

Each ADR follows the Nygard-style template: Date + Status, then Context, Decision, Consequences. ADRs carry no frontmatter — they are not a Diataxis type, and the project's diataxis_type/status frontmatter fields are decorative only, so extending them with a fifth fake "adr" value would misrepresent the taxonomy rather than describe it.

An ADR is superseded, never edited in place: when a later decision invalidates an earlier one, a new ADR is written and the old one is marked Status: Superseded by 00NN.

Reference: architecture-decision-record/architecture-decision-record.

Consequences¶

Future significant decisions (a new entity, a changed data-flow direction, an auth model change — anything a future reader would ask "why was it built this way?" about) get an ADR instead of an inline narrative admonition. Explanation pages link to the relevant ADR for rationale instead of restating it.