This page is the index for Architecture Decision Records (ADRs) for Kalix. ADRs capture why the codebase is the way it is — the significant decisions, the options that were considered, and the trade-offs accepted.

Where ADRs live

ADRs are canonical in the repository, not in Notion. They live as markdown files under:

docs/adr/

in the Kalix GitHub repo. This means:

• ADRs are versioned alongside the code they justify.
• New ADRs are proposed and reviewed in pull requests, at the moment the decision is being made.
• The full history survives independently of any external service.
• Anyone who clones the repo has the complete decision log.

This Notion page exists as a discoverability layer for non-developer readers (modellers, government collaborators, academic users) and a place to explain the convention.

Conventions

• One file per decision. Filename: NNNN-short-kebab-case-title.md, e.g. 0007-use-ini-format-for-model-files.md.
• Numbers are sequential and never reused, even if an ADR is later deprecated or superseded.
• ADRs are immutable once accepted. If a decision changes, write a new ADR that supersedes the old one. Update the old ADR's status to Superseded by ADR-NNNN but otherwise leave it intact.
• Status values: Proposed → Accepted → (optionally) Deprecated or Superseded by ADR-NNNN.
• Scope. Write an ADR for decisions that are hard to reverse, affect multiple components, set a precedent, or that future contributors are likely to question. Don't write one for routine refactors or cosmetic choices.

Workflow

1. Open a pull request adding docs/adr/NNNN-title.md with status Proposed.
2. Discuss in the PR — the PR thread becomes part of the decision's audit trail.
3. On merge, update status to Accepted.