Architecture Decision Records (ADR)¶

An Architecture Decision Record captures a significant technical decision and its context, so the reasoning survives the people who made it. dichit-backend keeps ADRs under docs/adr/ as numbered, immutable documents.

Why ADRs¶

• Explain the why behind non-obvious choices (layering, ORM, queues, pub/sub).
• Onboard new engineers and prevent re-litigating settled decisions.
• Preserve alternatives that were considered and rejected.
• Complement the living docs: ADRs answer why, docs answer how.

Status lifecycle¶

Rules¶

1. One decision per ADR. Keep it focused.
2. Use the template (template.md); keep the section order.
3. Number sequentially: NNNN-title-slug.md (0001-…, 0002-…).
4. Status first, and change status when a later ADR supersedes it.
5. Write for a future reader who was not in the conversation.
6. Keep it short — a few paragraphs per section, not a novel.
7. Link related ADRs and the docs they affect.

Writing one¶

Copy template.md → 000N-slug.md, fill it in, and open it in the same PR as the change. See 0001-example.md for a worked example.

Index¶

Related¶

• contributing.md
• architecture/overview.md