Skip to main content

ADRs and Decision Records

Why this chapter matters​

  • Prevents important frontend decisions from living only in meetings, pull requests, or one engineer's memory.
  • Gives future teams the context they need before changing rendering, state, module, design-system, or security decisions.
  • Reduces repeated debate by recording what was chosen, why it was chosen, and what consequences were accepted.

Core mental model​

An Architecture Decision Record is a short document for one significant decision. It should capture the context, the decision, the alternatives considered, and the consequences. The value is not the file itself. The value is preserving reasoning at the moment when tradeoffs were visible.

Frontend ADRs are useful when a decision changes how teams build or operate the product:

  • rendering strategy for a class of routes
  • state ownership model
  • API/BFF contract shape
  • design-system primitive policy
  • CSP, Trusted Types, or authentication handling
  • performance budget policy
  • module boundary and dependency rules

Do not write ADRs for every small implementation choice. Use them when the cost of forgetting the reasoning is higher than the cost of writing it down.

Decision framework​

QuestionGood ADR answer
What problem forced the decision?Names product and technical constraints
What options were considered?Includes serious alternatives, not strawmen
What did we choose?Clear enough to guide implementation
What consequences do we accept?Names costs, risks, and follow-up work
When should we revisit?Defines a date, metric, or trigger

Implementation pattern​

# ADR-012: Use URL-owned report filters

## Status
Accepted

## Context
Atlas users share report views with teammates and support. Current local filter state is lost on refresh, cannot reproduce bug reports, and allows API cache keys to diverge from visible UI state.

## Decision
Report filters that affect query results will be encoded in the URL. Ephemeral panel UI state remains local.

## Consequences
- Shared links reproduce report views.
- Filter parsing must be versioned and validated.
- URLs may become longer, so filter schema must stay compact.
- Components must not treat local state as the source of truth for result-bearing filters.

## Revisit trigger
Revisit if URL length exceeds browser or support-tool constraints, or if saved reports require server-owned filter state.

Anti-patterns and failure modes​

  • Decision diary: ADRs describe what happened but not why. Prevention: require options and consequences.
  • Approval theater: ADRs become a slow permission process for small choices. Prevention: classify decision significance.
  • Stale accepted decisions: constraints change but ADR status never changes. Prevention: add revisit triggers.
  • Tool worship: the team debates ADR format instead of decision quality. Prevention: keep the template short.
  • Hidden dissent: alternatives are omitted, so future teams repeat the same debate. Prevention: record rejected options fairly.

Verification checklist​

  • The ADR names a real decision, not a vague direction.
  • Context includes product, technical, team, and time constraints.
  • Alternatives are plausible.
  • Consequences include costs and risks.
  • Revisit trigger is explicit.
  • Implementation tasks link back to the ADR.

Metrics and scorecards​

Leading indicators:

  • percent of architecture-significant changes with decision records
  • number of reopened debates where an ADR provided useful context
  • ADRs with owner and revisit trigger

Lagging indicators:

  • migration cost caused by undocumented decisions
  • production incidents linked to misunderstood architecture
  • onboarding time for new tech leads

Exercises​

  • Write an ADR for choosing URL state versus local state for Atlas report filters.
  • Take a past frontend decision and add the consequences section you wish existed.
  • Review an ADR and identify what signal would prove the decision is still valid.