Skip to content

ADR-0001: Record architecture decisions

  • Status: Accepted
  • Date: 2026-10-02
  • Deciders: Luke Dixon
  • Ticket: PPL-4171
  • Supersedes: none

Context

The reasoning behind the platform's shape is spread across Confluence Plan decision logs, RCAs, PR threads and Slack. Plan decision logs are scoped to one piece of work and stop being read once it ships. PR threads are hard to find and Slack history is not durable. New engineers and AI agents working in the repo see what the code does but not why it was built that way, so settled questions get re-argued and constraints get broken by accident.

The team ownership page also had an open question: where are cross-team architecture decisions made and recorded?

Decision

We will record architecturally significant decisions as Architecture Decision Records in docs/architecture/decisions/, one Markdown file per decision, using the template and the process on the ADR index.

  • ADRs are proposed, reviewed and accepted through a PR. Merging the PR is acceptance.
  • Accepted ADRs are immutable apart from their status line; a changed decision gets a new, superseding ADR.
  • ADRs live in the monorepo, not Confluence, so they are versioned with the code, visible to AI agents working in the repo, and published on the engineering docs site.

Options considered

Option A: ADRs in the monorepo (chosen)

  • Good, because the record sits next to the code it explains and changes go through the same review as code.
  • Good, because agents and IDE search read it without extra tooling.
  • Bad, because product and clinical colleagues who live in Confluence are less likely to see it. Mitigated by linking ADRs from Plan decision logs.

Option B: ADRs as Confluence pages

  • Good, because DPPD documents already live there.
  • Bad, because Confluence pages drift from the code, have no review gate, and are not visible to agents without an MCP lookup.
  • Rejected because the audience for these decisions is mainly engineers changing the code.

Option C: Keep using Plan decision logs only

  • Good, because no new process.
  • Bad, because decision logs are tied to one Plan and are not found once it ships, and work that never had a Plan has no log at all.
  • Rejected because it is the status quo that caused the problem.

Consequences

  • Significant technical decisions now need a short written record and a reviewed PR, which adds a small amount of effort to those changes.
  • Reviewers can ask "where is the ADR?" for a change that sets a new direction, as listed in the PR review checklist.
  • Existing decisions are not backfilled in bulk. Write an ADR for an existing decision when it is next questioned or changed.
  • Revisit this process if ADRs stop being written for decisions that clearly needed one, or if the register becomes a list of Proposed records that never merge.