Architecture Decisions

Architecture decision records capture why a choice was made, what was rejected, and when the decision should be revisited. Keep them short and useful.

When to write an ADR

Write an ADR when a decision changes one of:

• Runtime platform or cloud service selection.
• Public APIs, events, schemas, or module boundaries.
• Security, identity, networking, or data handling posture.
• Deployment, rollback, observability, or incident response model.
• A major vendor, database, framework, or integration.

Do not write ADRs for trivial implementation details. Do write ADRs for choices that future teams will otherwise reverse-engineer from code.

ADR template

# ADR-NNN: Decision title

## Status

Proposed | Accepted | Superseded | Deprecated

## Context

What problem are we solving? What constraints matter?

## Decision

What did we choose?

## Consequences

What improves? What gets harder? What risks remain?

## Alternatives considered

What did we reject and why?

## Review trigger

What event, date, or metric should cause reconsideration?

Operating model

• Store ADRs near the system they describe or in a central architecture directory.
• Link ADRs from service catalogs, design docs, and relevant runbooks.
• Mark superseded decisions instead of deleting history.
• Review old ADRs during major migrations and incident follow-ups.

ADRs are not bureaucracy when they prevent repeated argument and lost context. If nobody can find or update them, the process is broken.