Architecture Decision Records

Architecture Decision Records

Reference Files

When to Use This Skill

• Making significant architectural decisions
• Documenting technology choices
• Recording design trade-offs
• Onboarding new team members
• Reviewing historical decisions

Core Concepts

What is an ADR?

An Architecture Decision Record captures:

• Context: Why we needed to make a decision
• Decision: What we decided
• Consequences: What happens as a result

When to Write an ADR

ADR Lifecycle

Proposed -> Accepted -> Deprecated -> Superseded
               |
            Rejected

Templates

Template 1: Standard ADR (MADR Format)

# ADR-0001: Use PostgreSQL as Primary Database

## Status

Accepted

## Context

We need to select a primary database for our new e-commerce platform. The system
will handle:

- ~10,000 concurrent users
- Complex product catalog with hierarchical categories
- Transaction processing for orders and payments
- Full-text search for products
- Geospatial queries for store locator

The team has experience with MySQL, PostgreSQL, and MongoDB. We need ACID
compliance for financial transactions.

## Decision Drivers

- **Must have ACID compliance** for payment processing
- **Must support complex queries** for reporting
- **Should support full-text search** to reduce infrastructure complexity
- **Should have good JSON support** for flexible product attributes
- **Team familiarity** reduces onboarding time

## Considered Options

### Option 1: PostgreSQL

- **Pros**: ACID compliant, excellent JSON support (JSONB), built-in full-text
  search, PostGIS for geospatial, team has experience
- **Cons**: Slightly more complex replication setup than MySQL

### Option 2: MySQL

- **Pros**: Very familiar to team, simple replication, large community
- **Cons**: Weaker JSON support, no built-in full-text search

### Option 3: MongoDB

- **Pros**: Flexible schema, native JSON, horizontal scaling
- **Cons**: No ACID for multi-document transactions, limited team experience

## Decision

We will use **PostgreSQL 15** as our primary database.

## Rationale

PostgreSQL provides the best balance of ACID compliance, built-in capabilities
(full-text search, JSONB, PostGIS), and team familiarity.

## Consequences

### Positive

- Single database handles transactions, search, and geospatial queries
- Reduced operational complexity (fewer services to manage)
- Strong consistency guarantees for financial data

### Negative

- Need to learn PostgreSQL-specific features
- Vertical scaling limits may require read replicas sooner
- Some team members need PostgreSQL-specific training

## Implementation Notes

- Use JSONB for flexible product attributes
- Implement connection pooling with PgBouncer
- Set up streaming replication for read replicas

Template 2: Lightweight ADR

# ADR-0012: Adopt TypeScript for Frontend Development

**Status**: Accepted
**Date**: 2024-01-15
**Deciders**: @alice, @bob, @charlie

## Context

Our React codebase has grown to 50+ components with increasing bug reports
related to prop type mismatches and undefined errors.

## Decision

Adopt TypeScript for all new frontend code. Migrate existing code incrementally.

## Consequences

**Good**: Catch type errors at compile time, better IDE support, self-documenting
code.

**Bad**: Learning curve for team, initial slowdown, build complexity increase.

**Mitigations**: TypeScript training sessions, allow gradual adoption with
`allowJs: true`.

Best Practices

Do's

• Write ADRs early - Before implementation starts
• Keep them short - 1-2 pages maximum
• Be honest about trade-offs - Include real cons
• Link related decisions - Build decision graph
• Update status - Deprecate when superseded

Don'ts

• Don't change accepted ADRs - Write new ones to supersede
• Don't skip context - Future readers need background
• Don't hide failures - Rejected decisions are valuable
• Don't be vague - Specific decisions, specific consequences
• Don't forget implementation - ADR without action is waste