📜 Technical Decision Records (ADRs)

Documenting architectural and technical decisions for future reference.

What is an ADR?

An Architecture Decision Record captures a significant technical decision, its context, and its consequences. It creates institutional memory.

When to write an ADR

• Choosing a framework, library, or tool
• Changing database or infrastructure
• Defining API contracts or data models
• Establishing coding conventions
• Any decision that's hard to reverse

ADR template

# ADR-001: [Title]

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

## Context
What is the situation? What forces are at play?

## Decision
What did we decide to do?

## Consequences
### Positive
- ...

### Negative
- ...

### Neutral
- ...

Example

# ADR-003: Use PostgreSQL over MongoDB

## Status
Accepted

## Context
We need a primary database. Our data is relational (users, orders, products).
Team has strong SQL experience. We need ACID transactions.

## Decision
Use PostgreSQL 16 as the primary database.

## Consequences
### Positive
- Strong relational model fits our data
- ACID transactions for order processing
- Team expertise, no learning curve

### Negative
- Less flexible schema than MongoDB
- Need to manage migrations

### Neutral
- Can add pgvector later for embeddings

Best practices

• Number ADRs sequentially (ADR-001, ADR-002)
• Store in the repo (docs/adr/ or docs/decisions/)
• Never delete — mark as deprecated or superseded
• Keep them short — one page max
• Link ADRs to related tickets or PRs
• Review during onboarding