SA-201a · Module 3

Architecture Decision Records

3 min read

Architecture decisions that are not documented are decisions that will be revisited — not because they were wrong, but because nobody remembers why they were made. An architecture decision record (ADR) is a short document that captures what was decided, why it was decided, what alternatives were considered, and under what conditions the decision should be revisited. The ADR is not bureaucracy. It is the institutional memory that prevents the team from relitigating settled decisions every quarter.

  1. Title and Context A short title describing the decision and the context that necessitated it. "ADR-007: Use PostgreSQL for the analytics data store. Context: The analytics service requires complex queries across time-series data with joins to relational metadata." The context grounds the decision in the specific problem it solves.
  2. Decision and Rationale The specific decision and the reasoning behind it. "Decision: Use PostgreSQL with TimescaleDB extension. Rationale: Satisfies complex query requirements, supports time-series natively through TimescaleDB, team has PostgreSQL expertise, and the managed service option reduces operational burden." The rationale connects the decision to the evidence.
  3. Alternatives Considered The options that were evaluated and rejected. "Alternatives: ClickHouse (rejected: no managed service option, team expertise gap), MongoDB (rejected: complex join performance insufficient for query patterns), DynamoDB (rejected: analytics query patterns do not map to key-value access patterns)." The alternatives prove the decision was a choice, not a default.
  4. Consequences and Review Trigger The expected consequences of the decision and the conditions that would trigger a review. "Consequences: PostgreSQL operational overhead is manageable with managed service. TimescaleDB extension adds dependency. Review trigger: if data volume exceeds 10TB or query latency exceeds 500ms at the 95th percentile, evaluate ClickHouse migration." The review trigger makes the decision adaptive, not permanent.

Do This

  • Write an ADR for every significant architecture decision — the investment is fifteen minutes and the return is months of clarity
  • Include the review trigger — every decision should define the conditions under which it should be reconsidered
  • Store ADRs alongside the code they govern — they are documentation, not bureaucracy

Avoid This

  • Make architecture decisions verbally and assume everyone will remember the rationale
  • Write ADRs so long that nobody reads them — one page maximum, four sections, done
  • Treat ADRs as permanent — they are living documents with review triggers that invite reconsideration