Skip to main content

Architecture Decisions

Record of significant architectural decisions made across projects.

What is an ADR?​

An Architecture Decision Record (ADR) documents a significant decision and the context around it. ADRs help:

  • Remember why - Capture the reasoning when it's fresh
  • Onboard new team members - Understand past decisions
  • Avoid re-litigation - Reference decisions when questions arise
  • Learn from mistakes - Review when outcomes differ from expectations

ADR Index​

No ADRs yet. Create your first one when you make a significant decision!

When to Write an ADR​

Write an ADR when deciding:

  • Technology stack choices
  • Architecture patterns
  • Third-party service selections
  • Significant trade-offs

ADR Lifecycle​

  1. Proposed - Under discussion
  2. Accepted - Decision made
  3. Deprecated - No longer relevant
  4. Superseded - Replaced by another ADR

Creating an ADR​

Use the ADR Template and:

  1. Number sequentially (ADR-001, ADR-002, etc.)
  2. Give a clear, descriptive title
  3. Document options considered
  4. Explain the decision
  5. Note consequences (good and bad)