ADR Index

This file is the mandatory entrypoint for humans and AI agents before changing architecture, code, CI, migration flow, contracts, or the template reference domain model.

Read in this order:

1. Template Overview
2. this INDEX.md
3. the foundation ADRs
4. the ADRs for the change area you are touching

Foundation ADRs

Treat these ADRs as baseline reading for almost any non-trivial task:

• ADR-0000 - how decisions are recorded
• ADR-0001 - monorepo and bounded contexts
• ADR-0002 - spec-first and contract versioning
• ADR-0012 - layout and file placement rules
• ADR-0015 - quality gates, governance, and security baseline
• ADR-0016 - CI baseline for GitHub and Gitea
• ADR-0017 - backend testing baseline on pytest and Testcontainers
• ADR-0018 - typed contracts, repositories, and Unit of Work
• ADR-0019 - repository/query split and exhaustive layer contracts
• ADR-0020 - centralized error registry and typed HTTP error projection
• ADR-0021 - centralized observability bootstrap, structured logging, tracing, metrics, and GlitchTip
• ADR-0022 - grouped backend settings, nested env keys, and clearer config ownership
• ADR-0027 - machine-enforced parity between OpenAPI, backend routes/contracts, and frontend clients/types
• ADR-0028 - backend lifecycle ownership, shared resource reuse, and the operational contract of the system health reference slice
• ADR-2000 - template metadata and self-consistency enforcement

Reading Map By Change Area

Backend Platform

Paths:

• src/backend/api/
• src/backend/core/
• src/backend/runtime/
• src/backend/main.py
• src/backend/pyproject.toml
• migrations/
• alembic.ini
• backend-related docker/

Read additionally:

• ADR-0005
• ADR-0008
• ADR-0009
• ADR-0010
• ADR-0011
• ADR-0013
• ADR-0014
• ADR-0017
• ADR-0018
• ADR-0019
• ADR-0020
• ADR-0021
• ADR-0022
• ADR-0028

Backend Apps And Product Semantics

Paths:

• src/backend/apps/
• src/backend/tests/apps/

Read additionally:

• ADR-0013
• ADR-0014
• ADR-0017
• ADR-0018
• ADR-0019
• ADR-0020
• ADR-0028

If the change affects reference-domain semantics around trust, verification, quarantine, promotion, metadata, audit, state, or storage, also read:

• ADR-1000
• ADR-1001
• ADR-1002
• ADR-1003
• ADR-1004

Frontend

Paths:

• src/frontend/
• docs/frontend/
• frontend-related docker/

Read additionally:

• ADR-0008
• ADR-0027
• ADR-0023
• ADR-0024
• ADR-0025
• ADR-0026

Specs And Contract Tests

Paths:

• specs/
• tests/contract/

Read additionally:

• ADR-0008

Repo Automation, Governance, And CI

Paths:

• .github/
• .gitea/
• .pre-commit-config.yaml
• Makefile
• scripts/
• governance docs and templates

Read additionally:

• ADR-0007
• ADR-0015
• ADR-0016
• ADR-0021
• ADR-0022
• ADR-2000

ADR And Rule Changes

Paths:

• docs/adr/
• .aiassistant/rules/

Read additionally:

• ADR-0000
• ADR-0015
• ADR-2000

Maintenance Rules

• if an ADR scope changes, update this index
• if an ADR is related to other decisions, keep the Related ADRs section current
• if an architectural constraint changes, update both the ADR and .aiassistant/rules/
• if a new mandatory root artifact or control path is introduced, reflect it in the ADR set and in this index