Architecture Decision Record

ELI5 — The Vibe Check

An ADR documents WHY you made a technical decision, not just what you decided. Why PostgreSQL over MongoDB? Why microservices over monolith? Six months later when someone asks 'why did we do this?', the ADR has the answer. It's a diary for your architecture choices.

Real Talk

Architecture Decision Records are lightweight documents capturing significant architectural decisions, their context, options considered, and rationale. Stored as numbered markdown files in the repository. Format typically includes: title, status, context, decision, consequences. Maintained over time with superseded/deprecated statuses.

Show Me The Code

# ADR-001: Use PostgreSQL for primary database

## Status: Accepted

## Context
We need a database for user and order data.

## Decision
Use PostgreSQL over MongoDB.

## Consequences
- Strong consistency guarantees
- Rich query capabilities with JSON support
- Team has existing PostgreSQL expertise

When You'll Hear This

"The ADR explains why we chose event sourcing — read it before proposing alternatives." / "We create an ADR for every decision that would be hard to reverse."