Architecture Decisions

An Architecture Decision Record — ADR — is a short document that captures one decision: what we chose, what we considered, why we picked it, and what we expect to give up. ADRs exist so that someone joining the team two years from now can understand why the codebase is shaped the way it is without having to dig through Slack threads.

ADRs are not a replacement for ongoing architecture review. They are a memory aid for the consequences of choices that are otherwise invisible in the code.

When an ADR is required

Write an ADR when any of the following is true:

• A new external dependency that touches the runtime path: a new database, queue, cache, vendor API, or hosting platform.
• A change to how data is persisted or how it moves between services.
• A change to authentication, authorisation, or session handling.
• A change to how user data is processed by AI, including model selection, prompt strategy, and caching.
• A move away from a previously documented pattern, even if no new dependency is added.
• A decision to not do something that would be the obvious next step.

When in doubt, write one. Cheap to author, expensive to live without.

Format

Each ADR is a Markdown file in docs/adr/ named NNNN-short-title.md where NNNN is a zero-padded sequence number. The template:

# ADR NNNN — Title

**Status:** Proposed | Accepted | Superseded by ADR XXXX
**Date:** YYYY-MM-DD
**Deciders:** names

## Context

What problem are we solving? What constraints are we working within?

## Decision

What we are doing. One paragraph.

## Alternatives considered

- Option A — rejected because…
- Option B — rejected because…

## Consequences

What we gain. What we give up. What this makes harder later.

The Status field matters. An ADR is Proposed until it's reviewed; Accepted once it's signed off; Superseded when a later ADR overrides it. Superseded ADRs are never deleted — they remain as the historical record. The superseding ADR's number goes in the Status line.

Review process

Proposed ADRs are reviewed by Engineering Leadership and any owner whose area is affected. Review is asynchronous: comments on the PR, approval to merge. A single approver is enough for low-stakes decisions; security or AI decisions require the Security Lead and Head of Legal respectively.

Examples worth writing

A few ADRs already on the Castline backlog:

• "Pusher for real-time, not WebSocket directly" — captures why we accepted vendor lock-in for the speed-to-market.
• "OpenAI Assistants API for AI Diaries" — and the cost-control patterns we adopted alongside it.
• "Laravel Cloud for hosting" — and what we'd switch to if we outgrew it.
• "Image storage in S3-compatible CDN, not the database" — even though it's obvious, codifying it prevents drift.

What ADRs are not

Not status updates. Not designs. Not RFCs that need refinement. They are the decision, written down at the moment the decision is made, in a place future-you will find it. The hardest part is writing them when the decision still feels obvious. That's exactly when they're most useful.

Owned by

Engineering Leadership.