Architecture Decision Records

WHAT

Lightweight documentation capturing the context, decision, and consequences of significant technical choices. ADRs become the institutional memory of why things are built the way they are.

WHEN

Adopting new frameworks or technologies Choosing between architectural approaches Making database or infrastructure decisions Defining API design patterns Any decision that would be hard to reverse or understand later

KEYWORDS

ADR, architecture decision record, technical documentation, decision log, MADR, RFC, design decisions, trade-offs

Quick Decision: Should I Write an ADR?

Write ADRSkip ADRNew framework/language adoptionMinor version upgradesDatabase technology choiceBug fixesAPI design patternsImplementation detailsSecurity architectureRoutine maintenanceIntegration patternsConfiguration changesBreaking changesCode formatting

ADR Lifecycle

Proposed → Accepted → Deprecated → Superseded ↓ Rejected Never modify accepted ADRs - write new ones to supersede.

Template 1: Standard (Copy This)

• # ADR-NNNN: [Title]
• ## Status
• [Proposed | Accepted | Deprecated | Superseded by ADR-XXXX]
• ## Context
• [What is the issue? What forces are at play? 2-3 paragraphs max.]
• ## Decision
• We will [decision statement].
• ## Consequences
• ### Positive
• [Benefit 1]
• [Benefit 2]
• ### Negative
• [Drawback 1]
• [Drawback 2]
• ### Risks
• [Risk and mitigation]
• ## Related
• ADR-XXXX: [Related decision]

Template 2: Full (For Major Decisions)

• # ADR-0001: Use PostgreSQL as Primary Database
• ## Status
• Accepted
• ## Context
• We need to select a primary database for our e-commerce platform handling:
• ~10,000 concurrent users
• Complex product catalog with hierarchical categories
• Transaction processing for orders and payments
• Full-text search for products
• The team has experience with MySQL, PostgreSQL, and MongoDB.
• ## Decision Drivers
• **Must have** ACID compliance for payment processing
• **Must support** complex queries for reporting
• **Should support** full-text search to reduce infrastructure
• **Should have** good JSON support for flexible product attributes
• ## Considered Options
• ### Option 1: PostgreSQL
• **Pros**: ACID compliant, excellent JSONB support, built-in full-text search, PostGIS
• **Cons**: Slightly more complex replication than MySQL
• ### Option 2: MySQL
• **Pros**: Familiar to team, simple replication
• **Cons**: Weaker JSON support, no built-in full-text search
• ### Option 3: MongoDB
• **Pros**: Flexible schema, native JSON
• **Cons**: No ACID for multi-document transactions, team has limited experience
• ## Decision
• We will use **PostgreSQL 15** as our primary database.
• ## Rationale
• PostgreSQL provides the best balance of ACID compliance (essential for e-commerce),
• built-in capabilities (reduces infrastructure), and team familiarity.
• ## Consequences
• ### Positive
• Single database handles transactions, search, and geospatial
• Reduced operational complexity
• Strong consistency for financial data
• ### Negative
• Need PostgreSQL-specific training for team
• Vertical scaling limits may require read replicas
• ### Risks
• Full-text search may not scale as well as Elasticsearch
• **Mitigation**: Design for potential ES addition if needed
• ## Implementation Notes
• Use JSONB for flexible product attributes
• Implement connection pooling with PgBouncer
• Set up streaming replication for read replicas
• ## Related
• ADR-0002: Caching Strategy (Redis)
• ADR-0005: Search Architecture

Template 3: Lightweight (For Smaller Decisions)

# ADR-0012: Adopt TypeScript for Frontend **Status**: Accepted **Date**: 2024-01-15 **Deciders**: @alice, @bob ## Context React codebase has 50+ components with increasing bugs from prop type mismatches. ## Decision Adopt TypeScript for all new frontend code. Migrate existing code incrementally. ## Consequences **Good**: Catch type errors at compile time, better IDE support **Bad**: Learning curve, initial slowdown **Mitigation**: Training sessions, `allowJs: true` for gradual adoption

Template 4: Y-Statement (One-Liner)

# ADR-0015: API Gateway Selection In the context of **building a microservices architecture**, facing **the need for centralized API management and rate limiting**, we decided for **Kong Gateway** and against **AWS API Gateway and custom Nginx**, to achieve **vendor independence and plugin extensibility**, accepting that **we need to manage Kong infrastructure ourselves**.

Template 5: Deprecation ADR

• # ADR-0020: Deprecate MongoDB in Favor of PostgreSQL
• ## Status
• Accepted (Supersedes ADR-0003)
• ## Context
• ADR-0003 (2021) chose MongoDB for user profiles. Since then:
• MongoDB transactions remain problematic for our use case
• Our schema has stabilized and rarely changes
• Maintaining two databases increases operational burden
• ## Decision
• Deprecate MongoDB and migrate user profiles to PostgreSQL.
• ## Migration Plan
• 1. **Week 1-2**: Create PostgreSQL schema, enable dual-write
• 2. **Week 3-4**: Backfill historical data, validate consistency
• 3. **Week 5**: Switch reads to PostgreSQL
• 4. **Week 6**: Remove MongoDB writes, decommission
• ## Lessons Learned
• Schema flexibility benefits were overestimated
• Operational cost of multiple databases was underestimated

Directory Structure

docs/ └── adr/ ├── README.md # Index and guidelines ├── template.md # Team's ADR template ├── 0001-use-postgresql.md ├── 0002-caching-strategy.md ├── 0003-mongodb-user-profiles.md # [DEPRECATED] └── 0020-deprecate-mongodb.md # Supersedes 0003

ADR Index (README.md)

# Architecture Decision Records | ADR | Title | Status | Date | |-----|-------|--------|------| | [0001](0001-use-postgresql.md) | Use PostgreSQL | Accepted | 2024-01-10 | | [0002](0002-caching-strategy.md) | Caching with Redis | Accepted | 2024-01-12 | | [0003](0003-mongodb-user-profiles.md) | MongoDB for Profiles | Deprecated | 2023-06-15 | | [0020](0020-deprecate-mongodb.md) | Deprecate MongoDB | Accepted | 2024-01-15 | ## Creating a New ADR 1. Copy `template.md` to `NNNN-title-with-dashes.md` 2. Fill in template, submit PR for review 3. Update this index after approval

Tooling: adr-tools

# Install brew install adr-tools # Initialize adr init docs/adr # Create new ADR adr new "Use PostgreSQL as Primary Database" # Supersede an ADR adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL" # Generate index adr generate toc > docs/adr/README.md

Review Checklist

Before submission: Context clearly explains the problem All viable options considered Pros/cons balanced and honest Consequences documented (positive AND negative) During review: At least 2 senior engineers reviewed Affected teams consulted Security implications considered Reversibility assessed After acceptance: Index updated Team notified Implementation tickets created

NEVER

Modify accepted ADRs: Write new ones to supersede Skip context: Future readers need the "why" Hide failures: Rejected decisions are valuable learning Be vague: Specific decisions, specific consequences Forget implementation: ADR without action is waste Over-document: Keep to 1-2 pages max Document too late: Write BEFORE implementation starts