Architecture Decisions (Standards Repository)
Decision records explain why a stack or pattern was chosen. They are not the agent contract.
| Load for coding | Document |
|---|---|
| MUST | docs/conventions/ and AGENTS.md |
| MUST NOT (routine tasks) | docs/decisions/ |
| MAY (new dependency, trade-off review) | Relevant decision below |
Status lifecycle
| Status | Meaning |
|---|---|
| Proposed | Under discussion; not yet normative |
| Accepted | Active; canonical rules in conventions apply |
| Superseded | Replaced by another decision; link the successor in the old file header |
| Deprecated | No longer recommended; retained for history |
When superseding a decision, update the old file status in its header, add a row with status Superseded, and point Canonical rules at the new convention or decision.
Concern tags
Filter the index by area: backend, frontend, infrastructure, tooling, process.
When to Write a Decision Here
Write a new file in docs/decisions/ when the standards repo adopts a new org-wide technology or reverses an existing one. Project-specific decisions belong in the consumer repository under docs/decisions/, not in this repo.
Do not use docs/adr/. All decision records for this repository live in docs/decisions/ with kebab-case filenames (no numeric prefix). The manifest field decisionsRoot points here.
File naming: docs/decisions/{kebab-case-topic}.md (no numeric prefix).
Filing steps:
- Copy the template from
docs/conventions/shared/adr-template.md. - Add a row to the index table below with Canonical rules pointing at the convention file agents MUST follow.
- Commit the decision and any convention updates in the same pull request.
Active Decisions Index
| Decision | Status | Concern | Canonical rules (agents use this) |
|---|---|---|---|
| agentic-development-as-primary-model | Accepted | process | AGENTS.md, docs/conventions/shared/agentic-guardrails.md |
| clean-architecture-as-structural-foundation | Accepted | backend | docs/architecture/clean-architecture.md |
| cqrs-with-split-application-projects | Accepted | backend | docs/conventions/backend/application-layer.md |
| litebus-as-mediator | Accepted | backend | docs/conventions/backend/application-layer.md, api-layer.md |
| minimal-api-endpoint-classes | Accepted | backend | docs/conventions/backend/api-layer.md |
| contracts-projects-for-application-layer | Accepted | backend | docs/conventions/backend/application-layer.md |
| reactions-project-depends-only-on-abstractions | Accepted | backend | docs/conventions/backend/application-layer.md |
| architecture-tests-as-enforcement | Accepted | backend | docs/conventions/backend/testing.md |
| outbox-pattern-as-reliability-escalation | Accepted | backend | docs/conventions/backend/reliability.md |
| turborepo-as-monorepo-tool | Accepted | tooling | docs/conventions/shared/monorepo-structure.md |
| openapi-typescript-client-generation | Accepted | frontend | docs/conventions/frontend/data-fetching.md |
| authjs-v5-authentication | Accepted | frontend | docs/conventions/frontend/nextjs-app-router.md, data-fetching.md |
| animation-tailwind-first-framer-motion-escalation | Accepted | frontend | docs/conventions/frontend/components.md |
| idatabasecontext-over-per-aggregate-read-stores | Accepted | backend | docs/conventions/backend/query-read-strategy.md |
| transaction-pipeline-behaviors | Accepted | backend | docs/architecture/clean-architecture.md, infrastructure-layer.md |
| pagination-convention | Accepted | backend | docs/conventions/backend/query-read-strategy.md |
| opentelemetry-observability | Accepted | infrastructure | docs/conventions/backend/observability.md |
| api-versioning-policy | Accepted | backend | docs/conventions/backend/api-layer.md |
| signalr-for-real-time-updates | Accepted | infrastructure | docs/conventions/shared/realtime-updates.md |
| multi-tenancy-default | Accepted | backend | Project ADR required before implementation |
| adddd-executable-acceptance-tests | Accepted | backend | docs/conventions/backend/api-acceptance-tests.md, testing.md |
| validation-error-dual-contracts-placement | Accepted | backend | docs/conventions/backend/exception-hierarchy.md |