Architecture Decision Records (ADRs): Documenting the Why

Code comments explain *what*, but not *why* a particular architectural decision was made. **ADRs** are lightweight Markdown documents capturing context, options considered, and the decision chosen.

ADR Template

# ADR-001: Use PostgreSQL over SQL Server

## Status
Accepted

## Context
We need a relational database for application X. 
Options: SQL Server, PostgreSQL, MySQL.

## Decision
Use PostgreSQL because of licensing costs and JSON support.

## Consequences
Team needs training on pgAdmin. 
ARM templates change.

Key Takeaways

• Store ADRs in the repo (`docs/adr/`).
• ADRs are immutable. If a decision changes, write a new ADR superseding the old one.