0000 - Record architectural decisions as ADRs

How to record architectural decisions in Nexus

Last updated on: September 21, 2026

Status: Accepted
Date: 2026-04-19
Deciders: Nexus core team
Tags: process, documentation

Context and Problem Statement

Nexus spans multiple services (gateway, control-plane, auth, policy, ingest, audit, query, console, admin), two data stores with distinct consistency models (Postgres and ClickHouse), and a shared-crate boundary with Aegis governed by vortex-common-crates/contracts/shared-crates.md. Decisions that affect any of these surfaces need to be discoverable, reviewable, and stable across years. Informal discussion notes, Slack threads, and MR descriptions lose their context the moment the original participants rotate out.

The Helicone reference implementation studied in Helicone: Lessons Learned has 240+ Postgres migrations and 80+ ClickHouse migrations — visible evidence of reactive design without a decision trail. We do not want to repeat that pattern.

Decision Drivers

Work specifications reference decisions that must be recorded before implementation starts.
Reviewers need a consistent artifact shape to catch regressions against earlier decisions.
AI coding agents need a predictable location and template for “what are we doing and why”.
The shared-crate policy requires joint review for changes across Aegis and Nexus; decisions must be linkable from MRs.

Considered Options

MADR 3.0 ADRs under docs/decisions/ — canonical, well-supported template; files are small and diff-friendly.
Inline design docs inside work specifications — describe implementation, not decisions.
A wiki (Confluence / Notion) — not version-controlled with the code; breaks the air-gap story; hostile to AI agents.
No formal record — relied on by Helicone. The downsides are visible in their schema churn.

Decision Outcome

Chosen option: MADR 3.0 ADRs under docs/decisions/.

Filenames are NNNN-short-title.md with NNNN a zero-padded, monotonically increasing integer. Numbers are never reused, even for superseded ADRs. The next available number is reserved by opening a draft MR that creates the file.

Required sections (per MADR 3.0):

## Context and Problem Statement
## Decision Drivers (optional but encouraged)
## Considered Options
## Decision Outcome
## Consequences
## More Information (optional)

Status values: Proposed, Accepted, Rejected, Deprecated, Superseded by ADR-NNNN.

P0 vs backlog-listed ADRs

The four P0 ADRs (0000, 0001, 0005, 0011) land before the first platform-wide services merge. The backlog-listed ADRs (0002–0010) each merge with the feature that first requires the decision — see the backlog. This is deliberate: a decision authored long before its implementing code is a premature decision.

Process

Author opens a MR that adds the ADR in Proposed state.
Required reviewers are the owners of the affected service(s), plus a security reviewer if the ADR touches crypto, classification, audit, or policy.
Merge flips the status to Accepted (or Rejected with a short rationale).
Later decisions that change course add a new ADR in Accepted state and flip the earlier ADR to Superseded by ADR-NNNN. The earlier ADR is not deleted.

Consequences

Every non-trivial architectural choice has one linkable artifact.
MR descriptions cite ADRs by number; reviewers can detect scope creep when a MR introduces a decision without an ADR.
The doc-lint script scripts/check-adr-references.sh enforces that the foundational ADRs exist and are linked from the README.
There is a writing tax on new decisions. We accept this tax as the cost of not repeating the Helicone / Bifrost schema-churn pattern.