Architecture decision records

Why decisions need a durable record

Architecture diagrams show what is proposed or deployed. They rarely explain why a material choice was made, which alternatives were rejected, which controls depend on it, or when it should be reconsidered.

An architecture decision record, or ADR, preserves that reasoning in a short, versioned artifact.

What deserves an ADR

Record decisions that materially affect sovereignty, security, portability, cost, operability, assurance, or future options. Examples include:

• Deployment and administrative boundaries.
• Model acquisition, license, runtime, routing, and update approach.
• Artifact import and promotion architecture.
• Knowledge store and permission-enforcement pattern.
• Identity propagation and gateway policy.
• Egress, tool execution, and human-approval boundaries.
• Evidence storage, integrity, retention, and export.
• Provider dependency, portability, continuity, and exit.

Do not create an ADR for every low-level implementation detail. Record choices whose reversal would be expensive, risky, or control-relevant.

ADR structure

ADR ID and title:
Status: proposed | accepted | superseded | retired
Decision owner and date:
System, version, and scope:

Context and required outcomes:
Constraints and assumptions:
Relevant threats and control objectives:

Options considered:
Decision and rationale:

Positive consequences:
Negative consequences and limitations:
External dependencies:
Evidence required:
Implementation and verification actions:

Reconsideration triggers:
Reversal or migration approach:
Related ADRs and artifacts:

Make trade-offs explicit

A useful ADR does not present the selected option as universally best. It explains why it is acceptable for the defined system and boundary.

For example, selecting a managed model endpoint may improve operational maturity while introducing provider, egress, administrative-authority, and exit dependencies. The ADR should state those consequences and the controls or acceptance decisions attached to them.

Link decisions to controls and evidence

Reference control-objective IDs, threat-scenario IDs, diagram elements, and evidence requirements. This creates traceability:

Requirement -> threat or dependency -> decision -> control -> evidence -> review trigger

If a decision cannot be verified, state what implementation or evidence gap remains.

Maintain decisions through change

Do not rewrite historical reasoning silently. Supersede the old ADR with a new record and link them. Reconsider a decision when its assumptions, intended purpose, data classification, model, provider, boundary, threat profile, cost, support condition, or portability requirement changes materially.

ADRs are shared Academy content because every technical module makes control-relevant decisions. Module-specific chapters should reference this template and add only their local decision questions.