Skip to content

Architecture Decision Records (ADRs)

Historical record of significant architectural and technical decisions.

What Goes Here

ADRs document: - Technology choices (languages, frameworks, databases) - Architectural patterns and approaches - Significant design decisions - Trade-offs and alternatives considered

ADR Format

Each ADR should follow this structure:

---
title: "ADR-001: Use PostgreSQL for Primary Database"
status: accepted
date: 2025-11-23
---

# ADR-001: Use PostgreSQL for Primary Database

## Status
Accepted

## Context
[Describe the situation and problem]

## Decision
[State the decision clearly]

## Consequences
[Describe the impact - both positive and negative]

## Alternatives Considered
[List other options and why they weren't chosen]

Naming Convention

  • Use sequential numbering: 001-, 002-, etc.
  • Use kebab-case for the decision topic
  • Examples:
  • 001-use-postgres.md
  • 002-adopt-microservices.md
  • 003-choose-react-over-vue.md

ADR Status

  • Proposed - Under discussion
  • Accepted - Decision made and being implemented
  • Deprecated - No longer the current approach
  • Superseded - Replaced by a newer ADR (link to it)

Rules

  1. Never edit published ADRs - They are historical records
  2. If a decision changes, create a new ADR and mark the old one as superseded
  3. Include the date of the decision
  4. Explain the context and alternatives, not just the choice