Skip to main content

ADRs for the Capstone: Three Must-Write Decisions

What This Concept Is​

An Architecture Decision Record (ADR) is a short, append-only document that captures a single architecturally significant decision with its context, the decision itself, and its consequences. ADRs are the "commits" of architecture: small, individually reasoned, version-controlled, supersedable. In the capstone you write exactly three ADRs -- no fewer, no more -- covering the decisions that most shape everything else:

  1. ADR-001: Architectural style. Monolith, modular monolith, or services (concept 08).
  2. ADR-002: Primary datastore / persistence model. The database (Postgres, SQLite, DynamoDB) and the persistence pattern (CRUD, event-sourced, append-only, etc.).
  3. ADR-003: Deployment topology. Single region vs multi-region, serverless vs containers, managed vs self-hosted.

Why exactly three? Not because there are only three decisions worth recording -- capstones have dozens -- but because these three cover the one-way doors (concept 07 of S7 M05's reversibility). Other decisions (API style, test framework, CI provider) are recoverable and belong in code review or the design doc, not an ADR. Writing more ADRs at capstone scale usually means you are recording design decisions (concept 03 of S7 M05), not architecture.

Each ADR has three required sections (S7 M05 cluster 02 discipline):

  • Context -- what forces, constraints, and characteristics drove the decision.
  • Decision -- exactly what was chosen, in the imperative voice.
  • Consequences -- what follows, good and bad, in terms of characteristics, fitness functions, and future ADRs.

Optional sections (alternatives considered, reversibility classification) are strongly recommended at capstone scale. Keep each ADR under one page. Longer ADRs read as essays and stop being useful.

Why It Matters Here (In the Capstone)​

The capstone asks you to make big decisions under time pressure and defend them in 5 minutes. Without ADRs, you will either (a) under-commit -- leaving decisions "flexible" until week 4, when inertia chooses for you -- or (b) over-commit, making a decision and then forgetting its reasoning by defense time. ADRs force you to write the decision down at the moment you made it, so you can later answer "why?" with the text you wrote then, not a post-hoc rationalization.

ADRs also create the link between characteristics and implementation. ADR-001's Context section cites your top-3 characteristics; ADR-002's Decision section points to a fitness function that will enforce it; ADR-003's Consequences name what you are giving up (e.g., "multi-region availability is a non-goal until after defense"). The triangle -- characteristics <-> ADRs <-> fitness functions -- becomes the architectural skeleton of the whole doc.

Finally, ADRs are the instrument that makes supersession possible. If in week 4 you realize Postgres was the wrong choice, you don't erase ADR-002; you write ADR-004 that supersedes it with "status: supersedes ADR-002; superseded-by: n/a." A reader walks the chain and sees the evolution. This is the professional behavior the capstone rehearses.

Concrete Example(s) -- from a real capstone​

Example A -- ADR-001 for the inventory service:

# ADR-001: Modular monolith as the architectural style

## Status
Accepted (2025-01-05). Reversibility: one-way door for this capstone.

## Context
Top-3 characteristics: correctness, operability, offline availability.
Constraints: solo team, 6 weeks, zero ops budget, one production region.
Candidates considered: plain monolith, modular monolith, services.

## Decision
Adopt a modular monolith, single process, single deployable.
Module boundaries: scan-core, reports, persistence, http-adapter,
queue-adapter. Modules communicate via published APIs only.

## Consequences
+ One deploy target; one set of logs; simple local dev.
+ Module boundaries can become services later if needed.
- No team-size independence benefit (irrelevant for solo).
- Shared dependencies must be agreed across modules.
Fitness function (arch/module-boundaries.test.ts) enforces:
no imports into another module's `internal/` folder.
Linked ADRs: ADR-002 (store), ADR-003 (deploy). See design-doc Section 6.

ADR-002 for the inventory service:

# ADR-002: Postgres with append-only scan_event table

## Context
Correctness driver requires idempotent, auditable scan handling.
Alternatives: SQLite (single-node simplicity but bad for concurrent API);
DynamoDB (managed but unfamiliar and harder to run locally).

## Decision
Managed Postgres (Supabase free tier). scan_event is append-only;
on_hand is a materialized view. Transaction per scan.

## Consequences
+ Rich queries, familiar SQL, strong transactional guarantees.
+ Idempotency via unique (idempotency_key) constraint.
- Operational dependency on a managed service (single-region).
Fitness function (correctness/idempotency.test.ts): replay scan -> zero drift.
Supersedes: none. Superseded-by: none.

Example B -- ticketing platform ADR-001 excerpt (differs from inventory):

Decision. Modular monolith. Separate buyer and door-scan frontends; one API. Door-scan as separate container (PWA), not separate service. Consequences. Strong no-oversell invariant lives in one process; no distributed-locking complexity. Multi-device door-scan is an availability risk, mitigated by offline cache + post-sync reconciliation.

Example C -- finance aggregator ADR-003 excerpt:

Decision. Local-only deployment (Electron or packaged Python CLI). No cloud. Optional user-encrypted file storage (passphrase-derived key). Consequences. Privacy characteristic #2 is inherent to the architecture (no network surface to attack). Multi-device sync is a non-goal. This ADR is explicitly reversible via ADR-0xx if a future user asks for sync.

Common Confusion / Misconceptions​

  • "ADRs are for every decision." No. ADRs are for architecturally significant decisions -- those that are expensive to reverse and shape downstream work. Everything else is code review or a README note.
  • "ADRs are long essays." No. Capstone ADRs are under one page. Longer ADRs are not read, and unread ADRs are waste.
  • "ADRs record 'possibilities.'" An ADR records a decision, not options. Alternatives get one bullet each, with why they were rejected.
  • "Delete an ADR when the decision changes." Never. ADRs are append-only. Write ADR-004 that supersedes ADR-002 with Status: supersedes ADR-002. The history is the value.

How To Use It (In Your Capstone)​

  1. Create library/raw/adrs/ with three files on day 1 of week 1, with placeholder Status: Proposed, and link them from design-doc section 8.
  2. Write the Context first, using top-3 characteristics as the opening bullets. Each context must cite characteristics explicitly.
  3. Write the Decision in imperative voice, under 100 words. "Adopt modular monolith..." not "We considered and might go with..."
  4. Write Consequences as bullets -- good and bad, with at least one "non-goal made explicit" item.
  5. Every ADR must name a fitness function (concept 09) that enforces it. If you can't name one, the ADR is probably aspirational.
  6. Mark reversibility. One-way door (style, persistence, topology) means extra caution. Two-way door decisions typically do not need ADRs.
  7. Supersede, never delete. If week 4 teaches you the decision was wrong, write ADR-004 and link backwards.

See also (integrative)​

The entire ADR discipline is taught in S7 M05. The capstone is where you execute the smallest useful subset of that discipline.

External references (curation-validated this session):

Check Yourself​

  1. Can you name the three ADRs your capstone must have, and why each is a one-way door?
  2. Does each ADR's Context cite the top-3 characteristics explicitly?
  3. Does each ADR name a fitness function that enforces it?
  4. If in week 4 a decision becomes wrong, do you know how to supersede (not delete) the ADR?
  5. Is every ADR under one page?

Mini Drill or Application (Capstone-scoped)​

  • Drill 1 (30 min). Draft ADR-001 for your capstone style. Force the Context paragraph to cite your top-3 characteristics and at least two rejected alternatives with one-line reasons.
  • Drill 2 (30 min). Draft ADR-002 (datastore). In Consequences, name the fitness function that guards it. If you can't, the ADR is aspirational -- either write the check or pick a different store.
  • Drill 3 (20 min). Draft ADR-003 (deployment topology). In Non-Goals, write the concrete things you are giving up (e.g., multi-region, autoscaling, custom domain).
  • Drill 4 (15 min, week 3). Re-read all three ADRs. Could you defend each in two sentences? If not, the Decision section is too long or the Context is unclear -- rewrite.
  • Drill 5 (10 min, week 5). Practice the supersession move by drafting a hypothetical ADR-004 that would supersede ADR-002, just to internalize the mechanics.

Source Backbone​

Capstone design applies earlier architecture and domain material. These books are the source backbone for the decisions in this module.