Appendix D: Data System ADR Template

Purpose

Use this record for a data-system decision whose consequences will outlive the meeting that made it: choosing a source of truth, adding a cache or derived store, adopting a queue or stream, moving analytical data, changing a migration strategy, or altering a recovery promise.

A useful ADR preserves the choice while the evidence is still alive. It should let a future engineer answer five questions: What pressure forced a decision? What facts constrained it? Why did this option survive comparison? What burden did the team accept? What evidence would make the choice wrong?

Write the record before approval. An ADR completed after implementation can describe what exists, but it can no longer expose preference to defeat.

The Record

Copy the headings below into the repository that owns the decision. Replace every prompt; an unexplained blank is evidence that the decision is not ready.

ADR: [Concrete verb and object]

Name the action and boundary: Use Postgres as the source of truth for subscription state, not Subscription database.

• Status: Proposed / Accepted / Rejected / Deprecated / Superseded
• Decision date:
• Technical owner:
• Operational owner:
• Security and privacy reviewer:
• Data governance reviewer:
• Related records: workload fingerprint, invariant register, prototype results, migration plan, runbooks, superseding ADR

Proposed means nobody should build against the choice yet. Accepted authorizes implementation. Rejected preserves an option that was deliberately declined. Deprecated marks a decision still present in production but on an exit path. Superseded must link to the record that replaced it.

Context and Pressure

Describe the present system, the product or operational pressure, and the consequence of doing nothing. Write this so that a reader can understand the problem without knowing your preferred technology.

Name the boundary of the decision. Which facts, services, teams, regions, and consumers are inside it? What remains outside it?

Separate observations from forecasts. Link measurements, incidents, regulations, cost reports, or customer evidence. Label estimates and assumptions plainly.

Workload Evidence

Summarize only the evidence that can change the choice; link the full workload fingerprint when one exists.

• Data and authority: shape, authoritative source, derived copies, retention, deletion, and lineage.
• Reads: named operations and callers, result size, freshness need, latency target, and failure behavior.
• Writes: command shapes, transaction boundaries, idempotency, ordering, concurrency, backfill, and deletion behavior.
• Scale: current size, expected growth, peak-to-average ratio, tenant skew, and hot-key risk.
• Correctness: critical invariants and the staleness, duplication, or reordering the workload can tolerate.
• Recovery: RPO, RTO, restore granularity, rebuild path, and the most recent proof.
• Protection: classification, access, audit, residency, retention, privacy, and abuse concerns.
• Operations and cost: owning team, on-call capability, current tooling, cost drivers, and budget boundary.

Avoid adjectives that cannot reject an option. “High scale,” “low latency,” and “strong consistency” become useful only when they name a volume, percentile, operation, boundary, or fact to preserve.

Invariants

Link the invariant register and repeat the critical facts that govern this decision. For each one, state where it is enforced, how it is tested, how production detects a violation, and how truth is repaired. If no single component can enforce the whole boundary, say how prevention and reconciliation divide the work.

Options Considered

Include the current system or a deliberate deferral when either is viable. Compare every candidate against the same workload and invariants. Product features, benchmark headlines, and general reputation are not substitutes for this comparison.

Record rejected options fairly. State the condition under which a rejected option would become preferable; this keeps the decision useful when the workload changes.

Decision

State the chosen option, the evidence that distinguished it, and the cost the team accepts. A decision sentence should be capable of being wrong:

We will [choice] because [workload and invariant evidence]. We accept [specific cost or limitation] rather than [cost or risk carried by the strongest alternative].

Name who has authority to accept the residual correctness, security, privacy, reliability, and cost risks. “Engineering approved” is not an owner.

Consequences

Describe what becomes easier, what becomes harder, and which work the decision creates. Include new dependencies, skills, capacity limits, consistency windows, recovery duties, and constraints on future changes. Do not repeat the sales case for the chosen system.

Failure Modes and Controls

Follow plausible failures far enough to change the design. Each row needs a user or operational consequence, a signal that arrives in time, and a first safe response.

If the pre-mortem produces no change to a test, guardrail, alert, runbook, cost limit, or reversal trigger, it has not yet influenced the decision.

Prototype Evidence and Uncertainty

Record the question each prototype tried to answer, the conditions of the test, the result, and the uncertainty that remains. Preserve links to reproducible fixtures and measurements. A test that cannot reject the preferred choice is a demonstration, not decision evidence.

Operational Acceptance

The operational owner accepts this section, including:

• user-facing read, write, freshness, lag, and correctness signals;
• actionable alerts and their responders;
• incident, repair, replay, backfill, rollback, and access-emergency runbooks;
• backup scope, RPO, RTO, restore owner, validation queries, and last drill result;
• service roles, human access, break-glass procedure, and audit review;
• capacity and cost drivers, budget, thresholds, and review cadence.

Link the dashboards and runbooks. If they do not exist yet, name the implementation owner and the condition that blocks cutover until they do.

Migration or Rollout

Describe compatibility changes, backfill, shadow or dual reads, canary scope, cutover, observation window, rollback window, and cleanup. For each phase, name the proof required to enter it and the condition that stops it. State which writes remain authoritative throughout; “dual write” alone does not resolve disagreement.

Reversal and Review

Name evidence that forces the decision back into review: a missed SLO, failed restore, unacceptable cost curve, repeated correctness incident, new regulated data class, multi-region requirement, large consumer, or workload change. Include thresholds where they are known.

Then describe the exit: how writes stop, data is exported or rebuilt, consumers move, incompatible schema is handled, and the old system is retired. Assign an owner. A reversible choice without a funded path is only theoretically reversible.

• Routine review date:
• Forced review triggers:
• Exit owner:
• Superseding ADR when triggered:

Acceptance Test

Before changing the status to Accepted, read the record as a hostile future maintainer:

1. Can the workload evidence reject at least one option?
2. Does every critical invariant have prevention, proof, production detection, and repair?
3. Were alternatives compared under the same constraints, including operating and exit costs?
4. Did prototype results expose uncertainty rather than merely confirm the favorite?
5. Do failure modes lead to owned signals and recoverable first actions?
6. Does rollout stop on named evidence, and does authority remain clear throughout migration?
7. Has the operational owner accepted the new surface?
8. Can new evidence trigger a review and a practical exit?

If the answer to one of these is no, leave the ADR Proposed. The missing answer is part of the decision, not paperwork to complete afterward.