Architecture Decision Records
ADRs capture significant architectural and design decisions that are hard to reverse, affect multiple stories, or will confuse future engineers.
Each ADR is immutable once
Accepted. Never modify an existing ADR — create a new ADR withSupersedes: ADR-NNNinstead.ADR gate (Story 041): Any architectural change MUST have an
AcceptedADR before implementation begins. CODEOWNERS enforces@architectapproval on all changes todocs/adr/.
ADR Registry
| ADR | Title | Status | Date | Superseded By |
|---|---|---|---|---|
| ADR-001 | PostgreSQL 16 Schema Design Standards | Accepted | 2026-02-21 | — |
| ADR-005 | IAM Domain Boundary — role management, audit logging, Keycloak sync | Accepted | 2026-02-21 | — |
| ADR-006 | Bulgarian Vehicle API Integration Strategy — МВР, АПИ, ГО, Виньетка | Accepted | 2026-02-25 | — |
| ADR-007 | Payment Gateway Selection for Membership Fees | Decision Deferred | 2026-02-25 | — |
ADR Lifecycle
Proposed → Accepted → Deprecated
↘ Superseded by ADR-NNN
Status Definitions
| Status | Meaning | Who can set it |
|---|---|---|
| Proposed | Written and submitted for review; not yet binding | Any agent |
| Accepted | Reviewed and approved by @architect — binding for all implementation | @architect only |
| Rejected | Reviewed and rejected — kept for history and reasoning | @architect only |
| Deprecated | No longer applicable but kept for historical context | @architect only |
| Superseded | Replaced by a newer ADR — link to replacement | @architect only |
Status Transition Rules
| From | To | Trigger | What must be updated |
|---|---|---|---|
| Proposed | Accepted | @architect approves the PR | ADR status field; this index table |
| Proposed | Rejected | @architect rejects with reasoning | ADR status field; add rejection reason to ADR body |
| Accepted | Deprecated | Decision is no longer valid (technology retired, etc.) | ADR status field; add deprecation note with date |
| Accepted | Superseded | New ADR replaces this one | Old ADR: status + link to new ADR; New ADR: Supersedes: ADR-NNN field |
When to Write an ADR
Requires an ADR
| Category | Examples |
|---|---|
| Docusaurus | Switching version, adding/removing major plugins, changing preset |
| ArgoCD | Changing sync strategy (manual ↔ auto), adding new watched component |
| Infrastructure | New service in docker-compose, new Traefik route, new external dependency |
| Database | New database technology, migration strategy change |
| Security | New auth mechanism, OAuth2 client type change, cookie policy change |
| Backend | New Spring module, new cross-cutting pattern (Outbox, Saga, CQRS) |
| Frontend | New state management library, UI framework change |
Does NOT Require an ADR
- Bug fixes and hotfixes
- UI copy changes
- Adding a new endpoint in an existing domain following established patterns
- Adding or improving tests
- Minor/patch version dependency bumps
Creating a New ADR
- Copy the template:
adr-template.md - Name the file:
adr-NNN-short-title.md(next sequential number) - Fill in all sections (Context, Decision Drivers, Considered Options, Decision Outcome, Consequences)
- Open a PR against
maininrcb-docusaurus - CODEOWNERS automatically requests
@architectreview - Do NOT start implementation until ADR status is changed to
Accepted - Reference the ADR in your implementation PR:
Implements ADR-NNN - Update this index table after the ADR is accepted