Architecture Decision Records
Document significant technical decisions so future you (and your team) understands why choices were made.
When to Write an ADR
Write one when you're making a decision that:
- Is hard to reverse later
- Affects multiple parts of the system
- Involves tradeoffs between valid options
- Will be questioned by someone in 6 months
Examples: choosing a database, adopting a framework, changing auth strategy, restructuring the API, adding a build tool.
Template
Create files in docs/decisions/ (or adr/) with sequential numbering:
markdown# ADR-001: Use PostgreSQL for primary database ## Status Accepted | Proposed | Deprecated | Superseded by ADR-XXX ## Date 2026-04-10 ## Context What is the problem or situation that requires a decision? Include constraints, requirements, and forces at play. ## Options Considered ### Option A: PostgreSQL - Pros: ACID compliance, JSON support, mature ecosystem, free - Cons: Requires managing connections, vertical scaling limits ### Option B: MongoDB - Pros: Flexible schema, horizontal scaling - Cons: No transactions across collections, eventual consistency issues ### Option C: PlanetScale (MySQL) - Pros: Serverless, branching, managed - Cons: Vendor lock-in, no foreign keys in their branching model ## Decision We chose **PostgreSQL** because: 1. Our data is relational — users, teams, projects with clear relationships 2. We need ACID transactions for billing operations 3. JSON columns give us schema flexibility where needed 4. Prisma/Drizzle have excellent Postgres support ## Consequences - We need to manage connection pooling (use PgBouncer or Prisma's built-in pool) - Migrations must be backwards-compatible for zero-downtime deploys - We accept vertical scaling limits and will shard later if needed
Workflow
- Identify the decision being made
- Research the options (at least 2-3 alternatives)
- Write the ADR using the template
- Review with the team (PR or discussion)
- Merge as accepted
- Reference from code comments when relevant:
// See ADR-001
File Naming
docs/decisions/ ├── 001-use-postgresql.md ├── 002-adopt-trpc-over-rest.md ├── 003-switch-to-pnpm.md └── template.md
Tips
- Keep ADRs short — 1-2 pages max
- Write them in the present tense ("We choose X" not "We chose X")
- It's OK to write an ADR after the fact if you forgot to write one during the decision
- Superseded ADRs should link to their replacement, not be deleted
- ADRs are not design docs — they capture the decision, not the full design
