Architecture Decision Records
An ADR records one decision that is costly to reverse: the context, what was decided, what was rejected and why, and what it costs. Write one when a change does any of the following:
- binds people outside this repo: forks consuming the library, the backend team, deployers or IdP operators;
- sets a rule every contributor must follow, such as a layering rule, a logging rule or a state-management idiom;
- has security impact;
- settles something that has been rewritten or argued about more than once.
A rule in CLAUDE.md says what to do. The ADR behind it says why, so
that the rule can be changed deliberately rather than eroded.
Index
| ADR | Title | Status | Date |
|---|---|---|---|
| ADR-001 | Reactive state management via scoped StateBus and ownership-based discovery |
Accepted | 2026-04-28 |
| ADR-002 | Customizable BrandTheme via a façade and a lowering buffer |
Accepted, amended by ADR-003 §1.3 | 2026-06-24 |
| ADR-003 | Reify the Flavor: a declaration object between composition and boot |
Accepted, amended by #536 | 2026-07-16 |
| ADR-004 | The AppModule composition contract |
Accepted (retroactive) | 2026-10-13 |
| ADR-005 | Module layering and cross-feature state | Accepted | 2026-10-13 |
| ADR-006 | The thread timeline model: runs, RunFold, bands and one layout |
Accepted (retroactive) | 2026-10-13 |
| ADR-007 | Thread labels: one curated catalogue, applied by owners and the assistant, with no visibility rules yet | Accepted | 2026-10-22 |
The repo-wide rule "Riverpod is DI only; signals carry state" is argued in ADR-001 §5.3, among the rejected alternatives.
Conventions
- File name.
ADR-NNN-kebab-case-title.md, three-digit and sequential. Numbers are never reused. - Status.
Proposed: under discussion, not yet in code.Accepted: decided, and the code follows it.Superseded: replaced by a later ADR, linked inSuperseded by.Deprecated: no longer applies and not replaced.
Move an ADR to Accepted in the PR that implements it.
- Changing an accepted ADR.
- Do not rewrite the decision. For a narrower change, add a dated
> **Amended by <ADR or PR> (YYYY-MM-DD):** ... note at the affected
section, and list it in the header's Amended by.
- When the change reverses the decision, write a new ADR and mark the old
one Superseded.
- Scope. One decision per ADR. A record that settles several independent
axes should list them in a "Decisions by axis" section, or be split.
- Update this index in the same PR that adds or changes an ADR's status.
Template
# ADR-NNN: <Decision, stated as an outcome>
- **Status:** Proposed
- **Date:** YYYY-MM-DD
- **Authors:** <names>
- **Supersedes:** —
- **Superseded by:** —
- **Amends:** — <optional: ADR-NNN §x>
---
## 1. Context and Problem Statement
What forces the decision. Cite code paths, issues and PRs.
## 2. Decision
The decision in a few sentences, plus a sketch or code shape if it helps.
## 3. The Decisions, by Axis
Optional. One subsection per independent sub-decision, each with its reason.
## 4. Consequences
What gets easier, what gets harder, and who is bound (forks, backend,
deployers, contributors). Name how the decision is enforced: a test, a lint,
a CI check, or review only.
## 5. Known Limitations and Open Questions
## 6. Migration
Omit for a retroactive record of a decision already in code.
## 7. Alternatives Considered
| Alternative | Why rejected |
| ----------- | ------------ |