This directory contains Architecture Decision Records - documentation of significant architectural decisions made during Promenade development.
An Architecture Decision Record (ADR) is a document that captures an important architectural decision made along with its context and consequences.
Purpose:
- Document the "why" behind architectural choices
- Preserve context for future developers
- Enable informed decision-making (avoid repeating past mistakes)
- Track evolution of architectural thinking
Each ADR follows this structure:
# ADR-NNNN: Title
**Status**: [Accepted | Rejected | Superseded | Deprecated]
**Date**: YYYY-MM-DD
**Deciders**: Name(s)
## Context
What is the issue we're seeing that is motivating this decision or change?
## Decision
What is the change that we're proposing and/or doing?
## Consequences
What becomes easier or more difficult to do because of this change?
### Positive
- ...
### Negative
- ...
### Neutral
- ...ADRs are numbered sequentially:
adr-0001-use-uuid-v7.md
adr-0002-use-sqlx-over-gorm.md
adr-0003-migrate-to-pgx-stdlib.md
| ADR | Title | Status | Date |
|---|---|---|---|
| 0001 | Use UUID v7 for Primary Keys | Accepted | 2026-01-15 |
| 0002 | Use sqlx Instead of GORM | Accepted | 2026-01-15 |
| 0003 | Migrate from lib/pq to pgx/v5/stdlib | Accepted | 2026-01-22 |
| 0004 | Use Redis for Caching Layer | Accepted | 2026-01-15 |
| 0005 | In-Memory Event Bus for Bounded Contexts | Accepted | 2026-01-18 |
| 0006 | Saga Pattern for Order Fulfillment | Accepted | 2026-01-20 |
-
Find next number:
ls docs/adr/*.md | tail -1 # Check last ADR number
-
Copy template:
cp docs/adr/adr-template.md docs/adr/adr-NNNN-title.md
-
Fill in details:
- Context: Why this decision is needed
- Decision: What was decided
- Consequences: Positive, negative, neutral impacts
-
Update README: Add entry to table above
-
Commit:
git add docs/adr/adr-NNNN-*.md git commit -m "docs: add ADR-NNNN for [decision]"
- Documenting Architecture Decisions by Michael Nygard
- ADR GitHub Organization
- When Should I Write an Architecture Decision Record
- docs/guides/ - Technical guides
- docs/concepts/ - Architectural concepts
- CHANGELOG.md - Project changelog