Architecture Decision Records

/architecture-decision-records

Create, maintain, and manage Architecture Decision Records (ADRs) that capture the context and rationale behind significant technical decisions. The user describes the decision (or pastes meeting notes, a design thread, or an existing ADR); deliver a complete, honest ADR as a markdown chat artifact ready to drop into their repo. For broader technical documentation (guides, references, runbooks), use technical-documentation.

When to Use

• Making significant architectural decisions
• Documenting technology choices
• Recording design trade-offs
• Reviewing historical decisions
• Establishing decision-making processes

Core Concepts

1. 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

2. When to Write an ADR

3. 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, a complex product catalog, transaction
processing for orders and payments, full-text product search, and geospatial
queries for a store locator. 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 (need
  Elasticsearch), no geospatial without extensions

### Option 3: MongoDB

- **Pros**: Flexible schema, native JSON, horizontal scaling
- **Cons**: No ACID for multi-document transactions (at decision time),
  team has limited experience, requires schema design discipline

## Decision

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

## Rationale

PostgreSQL provides the best balance of ACID compliance essential for
transactions, built-in capabilities (full-text search, JSONB, PostGIS) that
reduce infrastructure complexity, team familiarity, and a mature ecosystem.
The slight replication complexity is outweighed by not needing a separate
Elasticsearch service.

## 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 (JSONB, full-text search syntax)
- Vertical scaling limits may require read replicas sooner

### Risks

- Full-text search may not scale as well as dedicated search engines
- Mitigation: Design for potential Elasticsearch addition if needed

## Related Decisions

- ADR-0002: Caching Strategy (Redis) -- complements database choice
- ADR-0005: Search Architecture -- may supersede if Elasticsearch needed

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. PropTypes provide
runtime-only checking.

## 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`.

Template 3: Y-Statement Format

# ADR-0015: 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**.

Template 4: ADR for Deprecation

# ADR-0020: Deprecate MongoDB in Favor of PostgreSQL

## Status

Accepted (Supersedes ADR-0003)

## Context

ADR-0003 (2021) chose MongoDB for user profile storage due to schema flexibility
needs. Since then: multi-document transactions remain problematic for our use
case, our schema has stabilized, we now have PostgreSQL expertise from other
services, and maintaining two databases increases operational burden.

## Decision

Deprecate MongoDB and migrate user profiles to PostgreSQL.

## Migration Plan

1. **Phase 1** (Week 1-2): Create PostgreSQL schema, dual-write enabled
2. **Phase 2** (Week 3-4): Backfill historical data, validate consistency
3. **Phase 3** (Week 5): Switch reads to PostgreSQL, monitor
4. **Phase 4** (Week 6): Remove MongoDB writes, decommission

## Consequences

Positive: single database technology, ACID transactions for user data.
Negative: ~4 weeks migration effort, risk of data issues during migration,
some schema flexibility lost.

## Lessons Learned

- Schema flexibility benefits were overestimated
- Operational cost of multiple databases was underestimated
- Consider long-term maintenance in technology decisions

Template 5: RFC Style

For larger proposals, use an RFC structure: Summary, Motivation, Detailed Design (event schemas, projections, technology choices), Drawbacks, Alternatives, Unresolved Questions, Implementation Plan, References.

ADR Management

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)

Maintain a table of ADR number, title, status, and date, plus a short "Creating a New ADR" section. Statuses: Proposed, Accepted, Deprecated, Superseded, Rejected.

Automation (adr-tools)

brew install adr-tools
adr init docs/adr
adr new "Use PostgreSQL as Primary Database"
adr new -s 3 "Deprecate MongoDB in Favor of PostgreSQL"   # supersede ADR 3
adr generate toc > docs/adr/README.md
adr link 2 "Complements" 1 "Is complemented by"

Review Checklist

Before submission: context explains the problem, all viable options considered, pros/cons balanced and honest, consequences (positive and negative) documented, related ADRs linked.

During review: at least 2 senior engineers reviewed, affected teams consulted, security and cost implications considered, reversibility assessed.

After acceptance: index updated, team notified, implementation tickets created, related documentation updated.

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 a 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 -- an ADR without action is waste

Usage

/architecture-decision-records $ARGUMENTS