Technical Decision Records | The Garnet Wiki

Every engineering organization makes hundreds of technical decisions per year. Why did we choose PostgreSQL over MongoDB? Why is the API in Go instead of Python? Why do we use feature flags instead of long-lived branches? Six months later, nobody remembers. New engineers re-debate settled decisions. Context is lost.

Architecture Decision Records (ADRs) solve this by documenting the context, options considered, and rationale for every significant technical decision — creating a searchable, permanent record.

ADR Format

# ADR-042: Use PostgreSQL for the order service database

## Status
Accepted (2026-02-15)

## Context
The order service needs a persistent data store. Requirements:
- ACID transactions for payment processing
- Complex queries for reporting
- JSON support for flexible order metadata
- Team familiarity
- Managed hosting available on AWS

## Options Considered

### Option A: PostgreSQL
- Full ACID compliance
- Excellent JSON/JSONB support
- Strong ecosystem (extensions, tools, community)
- Team has 3 engineers with deep PostgreSQL experience
- AWS RDS provides managed hosting
- Cost: ~$200/month for production workload

### Option B: MongoDB
- Schema flexibility
- Horizontal scaling built-in
- Weaker transaction support (improved in v5+)
- 1 engineer with MongoDB experience
- Atlas provides managed hosting
- Cost: ~$250/month for production workload

### Option C: DynamoDB
- Unlimited scale, zero maintenance
- Limited query flexibility (requires careful key design)
- No team experience
- Vendor lock-in to AWS
- Cost: unpredictable under variable load

## Decision
PostgreSQL (Option A)

## Rationale
- Transaction safety is non-negotiable for payment processing
- JSONB provides the schema flexibility we need without sacrificing SQL querying
- Team experience reduces ramp-up time and operational risk
- Well-understood scaling path (read replicas, partitioning) for our projected growth
- Cost-effective and portable (no vendor lock-in)

## Consequences
- Must manage connection pooling (PgBouncer or application-level)
- Write scaling limited to vertical (acceptable for projected load)
- Need to set up replication for read-heavy reporting queries
- Team should document PostgreSQL-specific patterns in the wiki

## Review Date
2026-08-15 (6-month review to validate assumptions)

When to Write an ADR

Write an ADR when the decision:

Affects multiple teams or services
Is difficult or expensive to reverse
Has been debated more than once
Involves significant trade-offs
Sets a precedent for future decisions

Do NOT write an ADR for:

Variable naming
Code formatting choices (use a linter)
Library choice within a single module
Anything easily reversible in an afternoon

ADR Lifecycle

Proposed → Under Review → Accepted/Rejected → Superseded (optional)

Statuses

Status	Meaning
Proposed	Written, awaiting review
Under Review	Being discussed by stakeholders
Accepted	Decision made, implementation proceeding
Rejected	Considered but not adopted
Deprecated	No longer relevant (technology retired)
Superseded	Replaced by a newer ADR

Organization

docs/
└── adr/
    ├── 0001-record-architecture-decisions.md
    ├── 0002-use-postgresql-for-orders.md
    ├── 0003-adopt-event-driven-architecture.md
    ├── 0004-choose-typescript-for-frontend.md
    └── template.md

Numbering

Sequential numbering (0001, 0002, …) provides a chronological record. The sequence itself tells a story of how the architecture evolved.

Making ADRs Useful

Searchability

Store ADRs in the repository alongside the code they affect. When someone asks “why PostgreSQL?”, a simple grep finds the answer:

grep -r "PostgreSQL" docs/adr/

Cross-Referencing

ADRs should reference related decisions:

## Related ADRs
- ADR-003: Adopt event-driven architecture (influenced this choice)
- ADR-015: Use read replicas for reporting (consequence of this decision)

Regular Review

Schedule 6-month reviews for significant ADRs. Assumptions change, technology evolves, and decisions that were correct in 2025 may not be optimal in 2027.

Anti-Patterns

Anti-Pattern	Consequence	Fix
No decision records	Context lost, decisions re-debated	Start writing ADRs for new decisions
Too many ADRs	Nobody reads them	Only document significant, hard-to-reverse decisions
ADRs with no alternatives	Looks like a rubber stamp	Always include options considered
ADRs stored in a wiki nobody reads	Same as no ADRs	Store in repo, link from code comments
Never revisiting decisions	Outdated assumptions persist	6-month review dates on major ADRs

ADRs are the institutional memory of your engineering organization. When the engineer who made the decision leaves, the context stays.