Skip to main content

ADR Template

Architecture Decision Records document significant technical decisions.

Template​

# ADR-[NUMBER]: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded by ADR-XXX]

## Date
[YYYY-MM-DD]

## Context
[What is the issue that we're seeing that is motivating this decision or change?]

## Decision
[What is the change that we're proposing and/or doing?]

## Options Considered

### Option 1: [Name]
**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

### Option 2: [Name]
**Pros:**
- [Pro 1]
- [Pro 2]

**Cons:**
- [Con 1]
- [Con 2]

## Consequences

### Positive
- [Positive consequence 1]
- [Positive consequence 2]

### Negative
- [Negative consequence 1]
- [Trade-off we're accepting]

### Neutral
- [Neutral observation]

## References
- [Link to relevant documentation]
- [Link to discussion]

Example​

# ADR-001: Use PostgreSQL for Primary Database

## Status
Accepted

## Date
2024-01-15

## Context
We need to choose a primary database for our application. The application
will handle user data, transactions, and complex queries. We expect to
scale to 100k users in the first year.

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

## Options Considered

### Option 1: PostgreSQL
**Pros:**
- Excellent support for complex queries
- ACID compliance
- Strong ecosystem and tooling
- Free and open source

**Cons:**
- More operational overhead than managed NoSQL
- Horizontal scaling requires more effort

### Option 2: MongoDB
**Pros:**
- Flexible schema
- Easy horizontal scaling
- Good for document-oriented data

**Cons:**
- Less suitable for relational data
- Eventual consistency challenges
- Higher cost at scale

### Option 3: MySQL
**Pros:**
- Widely used and understood
- Good performance
- Many hosting options

**Cons:**
- Less feature-rich than PostgreSQL
- JSON support not as mature

## Consequences

### Positive
- Strong data integrity
- Powerful query capabilities
- Well-understood by team

### Negative
- Need to manage schema migrations
- Requires more planning for horizontal scaling

## References
- PostgreSQL documentation
- Team experience survey results

When to Write an ADR​

Write an ADR when:

  • Choosing a technology/framework
  • Deciding on an architecture pattern
  • Making trade-offs that affect the system
  • Decisions that would be hard to reverse

Don't write an ADR for:

  • Minor implementation details
  • Coding style choices (use a style guide)
  • Temporary solutions