name: Architecture Decision Records (ADR) description: Documenting significant architectural decisions with context, consequences, and rationale for future reference.

Architecture Decision Records (ADR)

Overview

Architecture Decision Records (ADRs) are lightweight documents that capture important architectural decisions, their context, and consequences. They create a historical record of why systems are built the way they are.

Core Principle: "Document the 'why' behind architectural decisions, not just the 'what'."

1. What is an ADR?

An ADR documents:

• What decision was made
• Why it was made (context)
• What alternatives were considered
• What the consequences are

When to Write an ADR

• Choosing a database (PostgreSQL vs MongoDB)
• Selecting an architecture pattern (microservices vs monolith)
• Picking a framework (React vs Vue)
• Defining API standards (REST vs GraphQL)
• Security decisions (OAuth2 vs JWT)

2. ADR Template (MADR Format)

# ADR-001: Use PostgreSQL for Primary Database

## Status
Accepted

## Context
We need a database for our e-commerce platform that handles:
- Complex transactions (orders, payments, inventory)
- ACID compliance requirements
- Relational data (users, products, orders)
- Expected scale: 100K users, 10K orders/day

## Decision
We will use PostgreSQL as our primary database.

## Alternatives Considered

### MongoDB
- **Pros**: Flexible schema, horizontal scaling
- **Cons**: Weaker transaction support, eventual consistency
- **Why rejected**: We need strong ACID guarantees for financial transactions

### MySQL
- **Pros**: Mature, widely used, good performance
- **Cons**: Less advanced features than PostgreSQL
- **Why rejected**: PostgreSQL's JSON support and advanced indexing better fit our needs

## Consequences

### Positive
- Strong ACID compliance for financial transactions
- Rich query capabilities (CTEs, window functions)
- JSON support for flexible product attributes
- Mature ecosystem and tooling

### Negative
- Vertical scaling limitations (can be mitigated with read replicas)
- More complex to operate than managed NoSQL solutions
- Learning curve for team members unfamiliar with SQL

## Implementation Notes
- Use Prisma ORM for type-safe database access
- Set up read replicas for scaling reads
- Use connection pooling (PgBouncer)

## Related Decisions
- ADR-002: Use Prisma ORM
- ADR-005: Database migration strategy

## Date
2024-01-15

## Authors
@alice, @bob

3. ADR Statuses

4. Directory Structure

docs/adr/
├── README.md
├── 0001-use-postgresql.md
├── 0002-use-prisma-orm.md
├── 0003-adopt-microservices.md
├── 0004-use-react-frontend.md
└── template.md

5. ADR Tools

adr-tools (CLI)

# Install
npm install -g adr-log

# Create new ADR
adr new "Use PostgreSQL for primary database"

# List all ADRs
adr list

# Generate table of contents
adr generate toc

Log4brains (Web UI)

# Install
npm install -g log4brains

# Initialize
log4brains init

# Preview
log4brains preview

# Build static site
log4brains build

6. Lightweight ADR Template

For smaller decisions:

# Use Tailwind CSS for styling

**Status**: Accepted
**Date**: 2024-01-15

## Decision
Use Tailwind CSS for all component styling.

## Rationale
- Utility-first approach speeds up development
- Consistent design system
- Smaller bundle size with PurgeCSS
- Team already familiar with it

## Consequences
- Need to learn Tailwind conventions
- HTML can become verbose
- Harder to share styles across projects

7. Superseding an ADR

# ADR-003: Adopt Microservices Architecture

## Status
~~Accepted~~ **Superseded by ADR-010**

## Superseded By
[ADR-010: Return to Modular Monolith](0010-modular-monolith.md)

## Original Decision
[Keep original content for historical reference]

## Why Superseded
After 2 years of microservices:
- Operational complexity exceeded benefits
- Team size (5 engineers) too small to manage 12 services
- Network latency impacting user experience
- Distributed tracing and debugging challenges

See ADR-010 for new approach.

8. ADR Review Process

## ADR Review Checklist

- [ ] **Context Clear**: Is the problem well-defined?
- [ ] **Alternatives Listed**: Were other options considered?
- [ ] **Trade-offs Analyzed**: Pros and cons documented?
- [ ] **Consequences Identified**: Both positive and negative?
- [ ] **Stakeholders Consulted**: Relevant teams reviewed?
- [ ] **Implementation Plan**: Next steps clear?
- [ ] **Date and Authors**: Documented?

9. Common ADR Topics

Technology Choices

• Database selection
• Programming language
• Framework selection
• Cloud provider

Architecture Patterns

• Microservices vs monolith
• Event-driven architecture
• CQRS and Event Sourcing
• API design (REST vs GraphQL)

Security

• Authentication method
• Encryption standards
• API security

Operations

• Deployment strategy
• Monitoring approach
• Logging standards

10. ADR Best Practices

Do

✅ Write ADRs for significant decisions ✅ Include alternatives considered ✅ Document trade-offs honestly ✅ Keep ADRs immutable (don't edit, supersede instead) ✅ Make ADRs easy to find (in repo, searchable)

Don't

❌ Write ADRs for trivial decisions ❌ Make ADRs too long (aim for 1-2 pages) ❌ Skip the "why" (context is crucial) ❌ Delete old ADRs (mark as superseded) ❌ Write ADRs after the fact (document during decision)

11. ADR Integration with Development

In Pull Requests

## PR Description

This PR implements the decision from [ADR-005: Use Redis for caching](../docs/adr/0005-redis-caching.md)

Changes:
- Add Redis client
- Implement cache layer
- Update documentation

In Code Comments

// Per ADR-003, we use JWT for authentication
// See: docs/adr/0003-jwt-authentication.md
export function verifyToken(token: string) {
  // ...
}

12. ADR Checklist

• Template Available: ADR template in repository?
• Directory Structure: Organized and numbered?
• Review Process: Who approves ADRs?
• Discoverability: ADRs linked in README?
• Tooling: CLI or web UI for managing ADRs?
• Integration: ADRs referenced in code/PRs?
• Maintenance: Old ADRs marked as superseded?
• Culture: Team writes ADRs consistently?

Related Skills

• 59-architecture-decision/tradeoff-analysis
• 59-architecture-decision/tech-stack-selection
• 59-architecture-decision/architecture-review
• 00-meta-skills/decision-making