Skip to content
Almathal Handbook

Architecture Decision Records

Accepted

This is the catalog of Architecture Decision Records (ADRs). Each ADR captures one architectural decision: the context in which it was made, the options considered, the decision reached, the rationale, and the resulting consequences.

ADRs are immutable once accepted. To change a decision, file a new ADR that supersedes the old one. The superseded ADR is kept in the log with its status updated.

How to Read an ADR

Each ADR is a short focused document. Read in numerical order to follow the design chain; read by topic to understand a specific decision. ADRs cross-reference each other where decisions depend on prior decisions.

ADR Status Values

  • Accepted — the decision is in force
  • Superseded — replaced by a later ADR (which it links to)
  • Deprecated — no longer in force, no direct successor
  • Proposed — drafted but not yet accepted

Catalog

Foundational Architecture

Schemas and Contracts

Pipeline and Sanity Checks

Registry and Curation

Scope and Composition

Migration

AI Governance and Security

Multi-User Governance

How to File a New ADR

When making a new architectural decision:

  1. Pick the next sequential number (currently 0033 would be next)
  2. Create a new MDX file at src/content/docs/decisions/00NN-short-slug.mdx
  3. Use the standard template (see existing ADRs)
  4. Mark status Proposed
  5. On acceptance, update status to Accepted and add to this index