Other architecture-decisions documentation engineering-practices

Architecture Decision Records: Capturing the Why Behind System Design

Architecture Decision Records: Capture the Why Behind System Design, with context, decision, alternatives, consequences, and revisit criteria
Architecture Decision Records: Capture the Why Behind System Design, with context, decision, alternatives, consequences, and revisit criteria

An architecture decision record (ADR) captures one significant design choice, the constraints behind it, and the costs the team accepts. It preserves reasoning that code and component diagrams rarely explain: why a design was chosen and what evidence would justify changing it.

ADRs are useful for decisions about data ownership, consistency, dependencies, and failure behavior. Their value depends on clear scope and reviewable evidence; a long document that records only benefits adds little protection against repeating an expensive mistake.

Table of Contents

Which Decisions Need an ADR?

Record decisions that constrain future work, cross ownership boundaries, or cost enough to reverse that their rationale matters. The right unit is a specific choice in a specific system, rather than a general explanation of a technology.

  • Service boundaries: Which component owns an order, and which operations may update it?
  • Consistency: Which reads must observe a completed write, and which may return older data?
  • Dependencies: Which external service becomes part of an availability or recovery commitment?
  • Operations: Which team owns reconciliation, capacity, migration, and incident response?

Routine implementation details usually belong in code or pull requests. Decisions about architectural boundaries deserve more context because they constrain later changes across components and teams.

Capture Constraints, Evidence, and Credible Options

Begin with the question and the boundaries of the decision. “Reduce reporting contention without changing checkout consistency” provides a reviewable objective; “adopt a faster database” leaves the workload, acceptable staleness, and failure behavior unspecified.

Label the basis of each claim. A staging benchmark is evidence for its tested workload, a traffic forecast is an assumption, and an agreed freshness requirement is a constraint. Preserve enough context to reassess each claim later.

RecordUseful detailWhy it matters
Workload evidenceDataset, query mix, concurrency, environment, and measurement window.Exposes where the result may stop applying.
Product constraintWhich views may be stale and what the freshness limit means.Prevents a technical optimization from changing a user-visible contract silently.
Operational capacityAvailable ownership, on-call coverage, and maintenance budget.Makes ongoing work part of the comparison.
UncertaintyMissing information, an owner, and the experiment needed to obtain it.Allows review before uncertain assumptions become expensive commitments.

Worked Example: Isolating Reporting from Checkout

Consider a fictional order service whose dashboard queries compete with checkout on one transactional database. The following requirements are illustrative assumptions, not measurements or universal production targets.

  • Dashboard summaries may lag committed data by up to one minute during normal operation.
  • Checkout confirmation must read authoritative transaction results.
  • The team can operate one additional database instance but cannot own an event-processing pipeline this quarter.
  • Reporting must degrade visibly instead of transferring unbounded load back to checkout.

Compare the Reporting Options

A read replica can isolate eligible reads while retaining the relational model. It introduces stale reads and another operational dependency, so the decision must specify which operations can tolerate replication delay.

OptionBenefitCost or limitation
Keep reports on the primaryMinimal additional infrastructure.Preserves contention unless query tuning or workload controls provide enough headroom.
Route reports to a read replicaSeparates read capacity without a new data model.Requires freshness handling, routing rules, and replica operations.
Maintain precomputed summariesReduces work for known report shapes.Adds refresh and invalidation decisions for each summary.
Build a separate reporting pipelineSupports an independent reporting model.Adds ingestion, reconciliation, schema evolution, and pipeline ownership.

The alternatives need enough detail to support a real choice. Precomputed summaries, including materialized views, are credible when queries repeat predictable aggregations. Their refresh cost and data freshness must be included in the comparison.

Record the Selected Boundary

The proposed decision routes dashboard reads and exports to a replica, while confirmation reads remain on the primary. If freshness cannot be established or exceeds the agreed limit, reports become unavailable or explicitly delayed according to the product contract.

  • Included: Dashboard summaries and scheduled exports whose contracts permit stale data.
  • Excluded: Checkout confirmation, authorization decisions, and reads that require immediate visibility of a completed write.
  • Fallback: Pause new exports when the replica is unavailable; any primary fallback must be explicitly bounded and capacity-tested.
  • Ownership: The orders team owns routing, freshness signals, query budgets, and recovery procedures.

Test Freshness and Failure Behavior

A report generation timestamp indicates when a report was assembled, not necessarily how current its source data was. Track an appropriate source freshness watermark or database-specific replication signal, and document its precision and behavior when the signal is missing.

  • Representative load: Exercise normal queries and expensive exports together; record checkout p95/p99 latency and database saturation.
  • Replica delay: Verify delayed-report behavior and confirm that the chosen signal reflects the freshness contract.
  • Replica failure: Check that connection timeouts, bounded pools, and export admission limits contain the impact.
  • Recovery: Resume exports gradually after freshness recovers; avoid releasing the entire deferred workload at once.

Acceptance thresholds must be agreed before the experiment. Persistent lag, a stricter freshness requirement, or a reporting model that no longer fits the transactional schema should trigger a new decision rather than an undocumented workaround.

A Reusable ADR Template

The template below keeps the decision, its rationale, ownership, and validation criteria together. It is a practical starting point; fields that add no useful information can be removed.

ADR 0017: Route eligible dashboard reads to a replica
Status: Proposed
Owner: Orders team
Reviewers: Database operations, checkout, reporting product owner

Question and scope:
Which workload is moving, and which reads remain authoritative?

Context:
Constraints, observed evidence, assumptions, and unresolved questions.

Options:
Credible alternatives and their important costs.

Decision:
Selected option, eligibility rules, exceptions, and fallback behavior.

Consequences:
Benefits, stale reads, new dependencies, operational work, and exit cost.

Validation:
Experiments, acceptance criteria, failure tests, and evidence links.

Revisit triggers:
Changes in requirements or observed behavior that justify reassessment.

Implementation and verification:
Linked delivery tasks and evidence of the deployed behavior.

Related decisions:
Earlier constraints and any record this decision replaces.

Acceptance is not rollout completion. An accepted ADR may describe a design that is still being implemented. Delivery tasks and post-deployment verification establish what actually runs; the decision record establishes what was agreed and why.

Review and Maintain the Decision History

Review should involve the people who carry the decision's costs, including operations and product owners where relevant. A design that reduces implementation effort may create reconciliation work or change customer expectations elsewhere.

  1. Propose: Write the scope and credible options before implementation makes the choice expensive to change.
  2. Challenge: Review evidence, exception paths, ownership, and reversal costs rather than technology preferences.
  3. Resolve: Record the accepted option or rejection and preserve material reasoning.
  4. Verify: Link implementation and rollout evidence, including any departures that require further review.
  5. Supersede: Create a replacement record when the agreed choice changes and link both directions.

Keep the original rationale when a decision is replaced. When incident findings invalidate earlier assumptions, the replacement record should link the relevant evidence and explain which constraint or guarantee changed.

Storage, Access, and Sensitive Data

A repository folder such as docs/decisions/ works when its readers already use version control. Cross-team decisions may need a stable index accessible to stakeholders outside the repository; avoid maintaining two independent authoritative copies.

Record access requirements without copying credentials, customer records, or restricted incident details into an ADR. Link appropriately protected evidence and summarize only the constraints that reviewers need to assess the choice.

Common Mistakes

Decision records become unreliable when they hide costs or blur the difference between intended behavior and evidence. The following errors undermine their value during later changes.

  • Recording only a product name: “Use database X” leaves contracts and ownership unresolved. State the workload, guarantees, exceptions, and responsibilities.
  • Presenting forecasts as evidence: An assumed traffic level can justify the wrong capacity choice. Label forecasts and attach the experiment needed to validate them.
  • Rewriting history after an incident: Replacing the old rationale obscures what was known. Add a linked successor that explains the changed evidence.
  • Using the ADR as proof of deployment: An accepted proposal can mislead responders if implementation is incomplete. Link verification of the running behavior separately.

Decision Review Checklist

A short review can expose missing commitments before approval. These checks apply to the record itself; the workload-specific validation plan still determines whether the design meets its requirements.

  • Scope: Identify included operations and explicitly excluded consistency or authorization paths.
  • Evidence: Link workload characteristics, experiment conditions, and measured results.
  • Alternatives: Compare credible options, including the cost of leaving the system unchanged.
  • Ownership: Assign responsibility for new infrastructure, recovery, and ongoing maintenance.
  • Reversal: Identify migration constraints and evidence that should trigger reassessment.

Frequently Asked Questions

ADRs coexist with other engineering documents. Their scope and authority should stay clear so the process remains useful when requirements or team ownership change.

How Does an ADR Differ from a Design Document or RFC?

An ADR preserves the outcome and rationale of one significant choice. A design document may explain an entire system, while an RFC gathers feedback on a proposal; one RFC can lead to several decisions that are recorded separately and linked back to the discussion.

Should Existing Systems Get Retrospective ADRs?

Yes, when a consequential decision is still constraining current work and its rationale can be reconstructed reliably. Mark the record as retrospective, distinguish confirmed facts from recollection, and leave unknown reasoning explicit instead of inventing an authoritative history.

Should Rejected Proposals Be Kept?

Keep rejected proposals when the analysis would prevent repeated investigation or explain a durable constraint. Record why the option was rejected and under which changed conditions reconsideration would make sense; retain less consequential discussion in the original review thread.

Conclusion

An ADR makes architectural reasoning reviewable across changes in code, requirements, and ownership. Its main cost is ongoing editorial care: scope, evidence, consequences, and status must remain clear enough for another engineer to reassess the choice.

Key Takeaway: Record a significant choice when its constraints and reversal costs matter, then define the evidence that would justify replacing it.

Comments (0)