Architecture Decision Records (ADRs)

This directory holds the long-form Architecture Decision Records for the BRAC POC. For short-form decisions (trade-offs logged quickly during the project), see DECISION-LOG.md.

Format

We use the MADR 3.0 format. Each ADR covers one significant architectural choice with its context, alternatives considered, and consequences.

Index

#	Title	Status
0000	Template	reference
0001	Use OpenTelemetry over proprietary APM	✅ Accepted
0002	Use Terraform for infrastructure automation	✅ Accepted

When to write a new ADR

Write an ADR (not just a DECISION-LOG entry) when:

• The decision has long-term architectural consequences (affects > 1 component, hard to reverse later)
• You evaluated 2+ serious alternatives worth documenting
• A future team member should understand the "why", not just the "what"
• The trade-offs are non-obvious or contested

For smaller choices (version pins, scoped refactors, vendor picks), a row in DECISION-LOG.md is enough.

How to add one

1. Copy 0000-template.md to 000N-<short-kebab-title>.md (next number).
2. Fill in all sections honestly — especially the Consequences and Pros / Cons tables.
3. Add a row to the index table above.
4. Add an entry to mkdocs.yml nav so it appears in the docs site.
5. Commit with message: docs(adr): add 000N — <title>.