ADR Index

Overview

Early in a project, it is tempting to skip written decisions. That saves time until the second or third teammate joins, a client integrates, or production breaks—then undocumented choices become expensive guesses. Use this index to read the rationale behind API behavior, security, testing, delivery, and docs. New decisions should start from the ADR template and follow ADR 0018 (lifecycle and ratification).

Architecture Decision Records (ADRs) explain what we decided, why it matters, and what we trade off—so the team does not re-litigate the same questions in chat or code review.
  • In scope: all ADRs under docs/adr/.
  • Out of scope: ADRs for API behavior, security, testing, delivery, and docs.

Startup reading guide

If you are new to the repo, you do not need every ADR on day one. Skim this page, then read groups in the order below—each group answers a different question new teams usually ask.

Process: how we record decisions

  • ADR 0018 — status on pages, Issues, PRs, and docs-only merges.
  • Template — structure for the next ADR.

Documentation & diagrams

  • ADR 0027 — client-side docs search: index construction, normalization model, ranking formula, and telemetry metrics/storage model.
  • RFC 0001 — deep implementation details for docs search: index schema, ranking internals, telemetry transport/storage, and troubleshooting.
  • Internal service documentation — engineering-facing behavior and semantics under docs/internal/; ADR 0025 (external vs internal), ADR 0026 (norms and authority).
  • Assessment reports (index) — template and indexes under docs/audit/ (docs/ vs api/ subtrees).
  • ADR 0024 — assessment (audit) documents: location, HTML format, tables, scoring, process.
  • ADR 0001 — docs in git, generation, quality gates.
  • ADR 0013 — changelog at the root and PR rules.
  • ADR 0016 — docstrings and pdoc.
  • ADR 0020 — C4, PlantUML, shared style.

API contract & integrators

  • ADR 0007 — OpenAPI quality and snapshots.
  • ADR 0003 — stable error codes and catalogs.
  • ADR 0004 — versioning and compatibility.
  • ADR 0006 — idempotent writes.
  • ADR 0022 — superseded browser validation note.

Security, config & supply chain

Testing & code health

Running, observing & SLOs

  • ADR 0009 — health, readiness, metrics.
  • ADR 0011 — SLOs, error budget, alerts.
  • ADR 0023 — structured logs, request id, optional local Elasticsearch.

Day-to-day workflow & Git

Containers & delivery

  • ADR 0015 — container image (Dockerfile, entrypoint).
  • ADR 0021 — CI push to GHCR.

Full index

Document Description Decision
Template Copy-paste shell for a new ADR: sections, ratification block, and the full status-milestone table for authors. —
ADR 0001 Docs as Code: narrative and generated docs live in git and pass the same quality gates as application changes. Accepted
ADR 0002 API changes must include automated tests (happy path + at least one failure); unfinished work does not ship. Accepted
ADR 0003 Stable machine-readable errors: shared transport catalog plus per-entity codes; OpenAPI and tests stay aligned. Accepted
ADR 0004 Major version in the URL; additive edits inside a major; breaking changes and error semantics need a deliberate path. Accepted
ADR 0005 Security baseline on protected routes: auth strategy, rate limits, CORS allowlist, headers, and request size cap. Accepted
ADR 0006 Critical writes use Idempotency-Key; server dedupes so retries do not double-apply business effects. Accepted
ADR 0007 OpenAPI is the product-facing contract: complete examples, links between operations, snapshots, and CI contract checks. Accepted
ADR 0008 Make targets split into small primitives versus high-level fix / verify / release-check entrypoints. Accepted
ADR 0009 /live vs /ready for orchestrators; Prometheus metrics for latency, status, and DB—same idea from laptop to prod. Accepted
ADR 0010 Explicit dev / qa / prod profiles, layered env files, and rules that block unsafe prod settings at startup. Accepted
ADR 0011 SLIs and SLOs (availability, latency, readiness), error-budget style burn signals, and Prometheus alerts—targets, not vibes. Accepted
ADR 0012 Testing map: required API and contract tests in CI; manual where it helps; load tests optional and tied to observability. Accepted
ADR 0013 Root CHANGELOG.md (Keep a Changelog), when CI expects an update, skip tokens, and optional LLM-assisted drafting. Accepted
ADR 0014 Hygiene: Ruff blocks unused imports on every PR; Vulture runs on a schedule for deeper dead code—delete only after triage. Accepted
ADR 0015 Reproducible Docker image (migrations + app entrypoint) for CI and registry pulls—not a full deployment platform. Accepted
ADR 0016 Google-style docstrings in Python; generated API HTML via pdoc so internal modules stay as reviewable as HTTP docs. Accepted
ADR 0017 Branch naming, trunk flow on main, semver tags, and how rare hotfixes get forward-ported. Accepted
ADR 0018 How ADR status is shown, how decisions are ratified (Issue + PR), and where doc-only changes are summarized. Accepted
ADR 0019 Pinned requirements.txt, pip-audit in Make/CI, severity-based response, and time-boxed exceptions. Accepted
ADR 0020 Architecture views in PlantUML using C4 levels, shared skin, sequence defaults, and Kroki-rendered PNGs in docs. Accepted
ADR 0021 After green CI on main / version tags, GitHub Actions builds the image and pushes to GHCR—runtime secrets stay outside the workflow. Accepted
ADR 0022 Superseded attempt at browser-side request validation; static explorer remains browse-only—contract checks live in CI. Superseded
ADR 0023 NDJSON logs, X-Request-Id, optional Docker Compose (Elasticsearch, Kibana, Filebeat) for local search—tracing in ES deferred to OpenTelemetry work. Accepted
ADR 0024 Architecture and quality assessments live under docs/audit/ as dated HTML: reference table, mapping/scores, findings, mitigation, history—complementing ADRs and runbooks. Accepted
ADR 0025 Split external (OpenAPI + changelog) vs internal (docs/internal/) documentation; OpenAPI baseline is the sole normative HTTP contract for integrators. Accepted
ADR 0026 Internal HTML under docs/internal/ is the authoritative engineering narrative for documented behavior, business rules, and ops expectations; history tables + git. Accepted
ADR 0027 Defines full-site client-side search for docs: offline index generation, lexical normalization, weighted relevance scoring, telemetry KPI formulas, and technical DB storage constraints. Accepted

Usage

  • Policy/architecture decisions → ADR.
  • Operational recovery procedures → Runbooks.
  • Engineering backlog (priorities and status) → Backlog.

Page history

Date Change Author
Added Page history section (repository baseline). Ivan Boyarkin