← All sessions & projects
Project 2 · Due Fri 19 June · after Sessions 3 & 4

Project 2: ADR #1: Database Decision

A one-page Architecture Decision Record choosing a data store for one feature, with the trade-off named.

What this is

Write a decision down so it survives you.

An ADR is a short record of a choice: what you decided, why, and what it cost. Tonight's is a database pick. The skill being graded is committing to one option and naming what you traded away.

💡 In plain English

An ADR is just a short note to your future team: "we chose X, here's why, here's what we gave up." It exists so nobody re-argues the decision in six months, or wonders what on earth you were thinking.

Do this, in order

The steps.

  1. 1
    State the contextWhat are you building, how is the data read and written, and what must always stay true? (Pull this straight from Session 3.)
  2. 2
    List 2–3 real optionsGenuine candidates, fairly described. No strawmen you set up just to knock down.
  3. 3
    Make the decision in one sentence"We will use ____." A clear commitment, not a "maybe" or a "it depends".
  4. 4
    Justify with the trade-offWhy this one, and explicitly what you gave up. Tie it to the access pattern or the invariant, not to popularity.
  5. 5
    Record the consequencesWhat is now easier, what is now harder, and the trigger that would make you revisit the choice.

The ADR format

Five fields, one page.

Title
ADR-001 ·
Status
Proposed / Accepted
Context
what we're building · how it's read & written · invariants · rough scale
Decision
"We will use ______ because ______."
Alternatives
______ (rejected because ___) · ______ (rejected because ___)
Consequences
easier: ___ · harder: ___ · revisit when: ___

How it's marked

What good looks like.

✓ Strong submission

  • The decision is one clear, committed sentence.
  • Alternatives are real and described fairly.
  • The justification ties to access patterns or invariants, not hype.
  • Consequences include a concrete revisit trigger.

✕ Common mistakes

  • Listing options and never actually committing.
  • Justifying by buzzword ("it's web-scale").
  • No downside named, so the choice sounds free.
  • Writing an essay; an ADR is one page.

Wrapping up

Hand in one ADR.

Use the five-field format above. Sessions 3 and 4 give you the options and the scale to defend them. One page.

Logistics
One-page ADR · five fields · due Fri 19 June.
submit on Maven
New to ADRs?
Search "Michael Nygard ADR" for the original one-pager. Steal the format.
it's meant to be short
For the instructorHow to teach thisclick to open ▾

The talk-track for introducing and explaining this project to students, beat by beat.

  1. 1

    Beginners may never have seen an ADR, so define it first, plainly: "It's a one-page note that records a decision and why. That's it. Not a spec, not an essay." Show a real one on screen if you can.

  2. 2

    Sell the why: "Decisions get re-argued endlessly when nobody wrote down the reasoning. An ADR ends that. It's also exactly what a promotion committee reads to see how you think."

  3. 3

    Walk the steps, and pre-empt the big fear: "You will feel unsure picking just one. That's the point, committing under uncertainty and saying why is the staff skill." Tie context back to Session 3's access-pattern lens.

  4. 4

    Walk the five-field template field by field. Spend longest on Decision and Consequences. Stress: the "because" and the revisit trigger are where the marks are, the rest is setup.

  5. 5

    Use the rubric to name the two classic failures: never committing, and naming no downside. "If your chosen option has no cost, you haven't found the real trade-off yet."

  6. 6

    Logistics, and reassure on length: "One page. If it's three pages you're writing a design doc, that's Project 5, not this." Point newcomers to the Nygard ADR template.