architecture-decision-records

Architecture Decision Records

Reference Files

File	When to read
references/templates-and-management.md	Need Y-Statement, Deprecation, or RFC-style ADR templates; ADR directory management; automation with adr-tools; review process checklists

---

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

Write ADR	Skip ADR
New framework adoption	Minor version upgrades
Database technology choice	Bug fixes
API design patterns	Implementation details
Security architecture	Routine maintenance
Integration patterns	Configuration changes

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