Madhura68
8a7d419972
Set up docs/adr/ as the canonical home for architecture decisions: - templates/nygard.md — default four-section format (Status, Context, Decision, Consequences) for one-way-door decisions. - templates/madr.md — MADR v4 with YAML front-matter and explicit Considered Options for decisions where rejected alternatives matter. - README.md — naming convention (NNNN-kebab-case), template-selection guidance (Nygard default; MADR for auth, queue mechanics, agent integration), status lifecycle, and ADR roster. - 0000-record-architecture-decisions.md — meta-ADR establishing the practice itself, in Nygard format. Backfilling existing implicit decisions (base-ui-over-radix, float sort_order, demo-user three-layer policy, etc.) is fase 6 of the docs-restructure plan.
93 lines
3.6 KiB
Markdown
93 lines
3.6 KiB
Markdown
---
|
|
title: Architecture Decision Records
|
|
status: active
|
|
audience: ai-agent, maintainer, contributor
|
|
language: en
|
|
last_updated: 2026-05-02
|
|
---
|
|
|
|
# Architecture Decision Records
|
|
|
|
This directory contains the Architecture Decision Records (ADRs) for Scrum4Me.
|
|
|
|
## What is an ADR
|
|
|
|
An ADR is a short document that captures a single significant architectural
|
|
decision: the context that forced the decision, the choice we made, and the
|
|
consequences of that choice. ADRs are immutable once accepted — if a later
|
|
decision changes course, we write a new ADR that supersedes the old one.
|
|
|
|
We use ADRs because the project mixes several non-obvious choices (Next.js 16
|
|
specifics, `@base-ui/react` over Radix, float `sort_order` for drag-and-drop,
|
|
iron-session over NextAuth, demo-user three-layer policy, MCP integration
|
|
patterns) and an AI agent reading the codebase six months from now needs to
|
|
find the *why* without spelunking through commit history.
|
|
|
|
## File naming
|
|
|
|
```
|
|
NNNN-kebab-case-title.md
|
|
```
|
|
|
|
- `NNNN` — four-digit zero-padded sequential number, starting at `0001`
|
|
(`0000` is reserved for the meta-ADR that introduces the practice).
|
|
- `kebab-case-title` — lowercase, hyphen-separated, short noun phrase
|
|
echoing the decision (`base-ui-over-radix`, not `decided-to-use-baseui`).
|
|
- Always `.md`.
|
|
|
|
## Choosing a template
|
|
|
|
Two templates live in [`templates/`](./templates/). Default to Nygard.
|
|
|
|
### Nygard (default — [`templates/nygard.md`](./templates/nygard.md))
|
|
|
|
Use Nygard for the common case: a decision that is essentially a one-way
|
|
door with a clear motivating context and one obvious choice. Four sections:
|
|
**Title, Status, Context, Decision, Consequences (Positive / Negative)**.
|
|
|
|
Aim: ≤60 lines. Reads in under a minute.
|
|
|
|
### MADR v4 (when alternatives matter — [`templates/madr.md`](./templates/madr.md))
|
|
|
|
Use MADR when the decision involves weighing multiple alternatives that a
|
|
future reader would otherwise re-litigate. Triggers:
|
|
|
|
- **Authentication / session strategy** (NextAuth vs iron-session vs Clerk).
|
|
- **Queue / messaging mechanics** (LISTEN/NOTIFY vs Redis vs SQS).
|
|
- **Agent integration patterns** (REST polling vs MCP vs SSE channel).
|
|
- **Schema or data-model choices with non-trivial migration cost.**
|
|
- Any decision where you want to record the *rejected* options so future
|
|
contributors don't propose them again.
|
|
|
|
MADR adds: YAML front-matter (status, date, decision-makers, consulted,
|
|
informed), explicit Decision Drivers, Considered Options, Pros and Cons of
|
|
each option, Confirmation, and More Information.
|
|
|
|
## Status lifecycle
|
|
|
|
```
|
|
proposed → accepted → (optionally) superseded by NNNN
|
|
↘ (optionally) deprecated
|
|
```
|
|
|
|
- **proposed** — drafted, awaiting decision-maker sign-off.
|
|
- **accepted** — current binding decision; the codebase reflects this.
|
|
- **superseded by ADR-NNNN** — replaced. Keep the file; never edit the
|
|
Decision section. Add a one-line "Superseded by …" note at the top of
|
|
the Status section and link to the new ADR.
|
|
- **deprecated** — still current but no longer recommended; usually a
|
|
precursor to a future supersession.
|
|
|
|
Once an ADR is accepted, it is immutable except for the Status field and
|
|
typo fixes. Course corrections always create a new ADR.
|
|
|
|
## Index of ADRs
|
|
|
|
| # | Title | Status | Template |
|
|
|---|---|---|---|
|
|
| [0000](./0000-record-architecture-decisions.md) | Record architecture decisions | accepted | Nygard |
|
|
|
|
When new ADRs are added, the docs index generator (`npm run docs:index`)
|
|
will list them in [`../INDEX.md`](../INDEX.md). Update this table by hand
|
|
when you add or supersede an ADR — the script aggregates across the whole
|
|
docs tree, this README is the canonical ADR-only roster.
|