Architecture Decision Records

Architecture Decision Records (ADR)

An Architecture Decision Record captures the context, decision, and consequences of significant technical choices. ADRs prevent re-litigating settled decisions and preserve institutional knowledge.

"Architecture is the stuff that's hard to change. Document why you chose it." — Michael Nygard

🎯 When to Write an ADR

Rule of thumb: If the decision will affect the team for >6 months, write an ADR.

📝 MADR 4.0.0 Template (Full)

MADR (Markdown Architectural Decision Records) is the industry standard. Version 4.0.0 was released September 2024.

---
status: proposed | accepted | rejected | deprecated | superseded by ADR-0012
date: 2024-01-15
decision-makers: [@alice, @bob]
consulted: [@charlie, @diana]
informed: [@team-backend]
---

# Use PostgreSQL as Primary Database

## Context and Problem Statement

We need a relational database for our e-commerce platform. The database must:
- Support ACID transactions for order processing
- Handle complex queries for reporting
- Scale to 10M+ products
- Have strong community support and tooling

## Decision Drivers

- **Data consistency:** Orders and payments require ACID guarantees
- **Query complexity:** Product search, order history, analytics need JOINs
- **Team expertise:** Team has 5+ years PostgreSQL experience
- **Operational cost:** Managed service availability (AWS RDS, GCP Cloud SQL)
- **Ecosystem:** ORM support, migration tools, monitoring

## Considered Options

- PostgreSQL
- MySQL
- MongoDB
- CockroachDB

## Decision Outcome

Chosen option: **"PostgreSQL"**, because it best satisfies our decision drivers:
- Full ACID compliance for financial transactions
- Advanced JSON support for flexible product attributes
- Excellent query planner for complex analytics
- Managed services available on AWS, GCP, Azure
- Team already proficient

### Consequences

- **Good**, because ACID transactions prevent data corruption in order processing
- **Good**, because JSONB columns allow flexible schema for product attributes without full NoSQL
- **Good**, because AWS RDS provides automated backups, failover, and patching
- **Bad**, because horizontal scaling requires read replicas or sharding (more complex than DynamoDB)
- **Bad**, because schema migrations require downtime or complex blue/green deployment

### Confirmation

- Validate: Run load test with 10M products + concurrent orders
- Revisit if: Write throughput exceeds 10K TPS or horizontal scaling becomes critical

## Pros and Cons of the Options

### PostgreSQL

- **Good**, because full ACID compliance and advanced SQL features
- **Good**, because JSONB provides document-like flexibility within relational structure
- **Good**, because mature ecosystem (PostGIS, full-text search, partitioning)
- **Bad**, because vertical scaling limits on single-node writes
- **Bad**, because schema changes require migration planning

### MySQL

- **Good**, because widely used, good performance for simple queries
- **Good**, because AWS Aurora provides excellent managed service
- **Bad**, because less advanced query planner for complex analytics
- **Bad**, because JSON support less mature than PostgreSQL JSONB

### MongoDB

- **Good**, because schema flexibility for rapidly changing product attributes
- **Good**, because horizontal scaling via sharding is native
- **Bad**, because eventual consistency unacceptable for financial transactions
- **Bad**, because team lacks operational experience
- **Bad**, because complex JOINs require application-level processing

### CockroachDB

- **Good**, because distributed SQL with horizontal scaling
- **Good**, because PostgreSQL-compatible wire protocol
- **Bad**, because higher operational complexity
- **Bad**, because smaller community, fewer managed service options
- **Bad**, because overkill for current scale (premature optimization)

## More Information

- [PostgreSQL vs MySQL comparison](https://www.postgresql.org/about/)
- [AWS RDS PostgreSQL](https://aws.amazon.com/rds/postgresql/)
- Related: ADR-0005 (Read Replica Strategy)

📝 MADR Minimal Template

For smaller decisions, use the minimal template:

---
status: accepted
date: 2024-01-15
---

# Adopt Ruff for Python Linting

## Context

We currently use flake8 + black + isort. Three tools with separate configs.

## Decision

Replace with Ruff — one tool, faster, compatible.

## Consequences

- **Good**: Single config file, 10-100x faster
- **Bad**: Team needs to learn new rule codes
- **Mitigation**: Migration guide in docs/python-tooling.md

📝 Y-Statement Template

For the fastest documentation (one sentence):

# Y-Statement: API Gateway Selection

In the context of **building a microservices architecture**,
facing **the need for centralized API management, authentication, and rate limiting**,
we decided for **Kong Gateway**
and against **AWS API Gateway and custom Nginx solution**,
to achieve **vendor independence, plugin extensibility, and team familiarity with Lua**,
accepting that **we need to manage Kong infrastructure ourselves**.

🏗️ ADR Directory Structure

docs/
├── adr/
│   ├── README.md              # Index and guidelines
│   ├── template.md            # Your team's MADR template
│   ├── 0001-record-architecture-decisions.md
│   ├── 0002-use-postgresql.md
│   ├── 0003-caching-strategy.md
│   ├── 0004-microservices-vs-monolith.md
│   ├── 0005-read-replica-strategy.md
│   ├── 0006-graphql-api.md
│   ├── 0007-event-driven-architecture.md
│   ├── 0015-adopt-kubernetes.md
│   ├── 0016-container-orchestration.md  # [SUPERSEDED by 0015]
│   └── 0020-deprecate-rest-v1.md        # Supersedes implicit earlier decision

ADR Index (README.md)

# Architecture Decision Records

## Index

| ADR | Title | Status | Date | Supersedes |
|-----|-------|--------|------|------------|
| 0001 | Record Architecture Decisions | Accepted | 2024-01-10 | — |
| 0002 | Use PostgreSQL as Primary Database | Accepted | 2024-01-15 | — |
| 0003 | Caching Strategy with Redis | Accepted | 2024-01-20 | — |
| 0004 | Start with Modular Monolith | Accepted | 2024-02-01 | — |
| 0005 | Read Replica Strategy | Accepted | 2024-02-15 | — |
| 0006 | GraphQL for Mobile API | Accepted | 2024-03-01 | — |
| 0007 | Event-Driven Architecture | Accepted | 2024-03-15 | — |
| 0015 | Adopt Kubernetes | Accepted | 2024-06-01 | 0016 |
| 0016 | Container Orchestration with Docker Swarm | Deprecated | 2024-01-30 | — |
| 0020 | Deprecate REST API v1 | Accepted | 2024-08-01 | — |

## Status Definitions

- **Proposed**: Under discussion, seeking feedback
- **Accepted**: Decision made, being implemented
- **Rejected**: Considered but not adopted
- **Deprecated**: No longer relevant, but was accepted
- **Superseded**: Replaced by a newer ADR

## Creating a New ADR

1. Copy `template.md` to `NNNN-title-with-dashes.md`
2. Fill in all sections
3. Submit PR for team review
4. Update this index after merge

🔄 ADR Lifecycle

┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│ PROPOSED │───▶│ ACCEPTED │───▶│DEPRECATED│    │ REJECTED │
└──────────┘    └────┬─────┘    └────┬─────┘    └──────────┘
                     │               │
                     │         ┌─────┘
                     │         ▼
                     │    ┌──────────┐
                     └───▶│SUPERSEDED│
                          │ by ADR-X │
                          └──────────┘

State Transitions

🛠️ Automation with adr-tools

# Install
brew install adr-tools

# Initialize ADR directory
adr init docs/adr

# Create new ADR (auto-numbers)
adr new "Use PostgreSQL as Primary Database"
# Creates: docs/adr/0002-use-postgresql-as-primary-database.md

# Supersede an ADR
adr new -s 3 "Use Redis Cluster for Caching"
# Creates new ADR that supersedes ADR-0003

# Link related ADRs
adr link 5 "Enables" 6 "Is enabled by"

# Generate table of contents
adr generate toc > docs/adr/README.md

🎯 Decision Quality Checklist

Before accepting an ADR, verify:

• Context is clear: Someone reading this in 2 years understands the problem
• Drivers are explicit: Criteria for evaluating options are stated
• Options are comprehensive: At least 3 alternatives considered (including "do nothing")
• Trade-offs are honest: Both good and bad consequences documented
• Decision is reversible: How hard to undo? (should be stated)
• Confirmation defined: How will we know this decision was correct?
• Stakeholders consulted: Decision-makers, consulted, informed listed
• Related ADRs linked: Dependencies and superseded decisions referenced

🚫 ADR Anti-Patterns

🔗 Integration with Other Skills

📚 References

• MADR 4.0.0 — Official specification
• ADR GitHub Organization — Templates and tools
• Documenting Architecture Decisions — Michael Nygard (original)
• Y-Statements — Sustainable Architectural Decisions
• adr-tools — Command-line tools