Appearance
Capstone Template — ADRs & Trade-off Review
Fill this in as you build. Copy the ADR block once per significant decision; complete the trade-off review after both builds. This is your capstone deliverable scaffold.
Before you start
My chosen decision axis: (one of: build-vs-buy · decomposition · consistency · sync-vs-async control flow · deterministic-vs-AI · data-store strategy)
...
Why this axis (the honest reason — ideally "it's the one I had the least exposure to"):
...
The axis I was second most tempted by (the trade-off review will ask where it pulled at you):
...
How to use this template
- Write ADRs as you build, not after — the context is honest only while it's fresh.
- Write one ADR per significant decision (the ones where someone would later ask "why is it like this?"), not for trivia. Aim for a handful per build.
- The consequences section is mandatory and must name costs. An ADR with only benefits is hiding the trade-off — the one thing the course refuses to let you do.
- Complete the trade-off review after both builds are done; it's the central deliverable.
- Keep ADRs short (a page or less each). Compression is part of the skill.
Throughout: name your two builds in plain language for your axis — e.g. A = in-house / B = 3rd-party, A = monolith / B = service-split, A = transactional / B = eventual, A = orchestration / B = choreography, A = deterministic / B = AI-augmented, A = single store / B = polyglot. Build A is the simpler/baseline version; build it first.
Part 1 — Build A (baseline)
Build A overview
A few sentences: which version of the feature this is, how it's structured, and what made it the simpler/baseline build along your axis.
Your overview here.
ADR template (copy once per decision)
ADR-A-NNN: [short noun phrase naming the decision]
Status: Accepted | Superseded by ADR-A-XXX
ContextThe situation forcing a decision. What's the problem? What constraints are binding? What quality attributes are in tension? Write it for a competent engineer who knows the system but wasn't in the room.
...
DecisionWhat you chose, stated plainly and actively.
...
ConsequencesWhat results — good AND bad. This section must honestly name what the decision costs, not just what it buys. If you can't name a cost, you haven't finished thinking.
- Positive:
...
- Negative / costs:
...
Part 2 — Build B (the alternative)
Build B overview
A few sentences: how this version differs from Build A along your axis, what new machinery it introduced, and what became possible (or newly hard) because of the change.
Your overview here.
(Copy the ADR template from Part 1 for each Build B decision, numbering them ADR-B-NNN.)
Suggested ADRs — by axis
Four ADRs are worth writing whatever axis you chose:
- The boundary you drew — where the seam between the two approaches sits, and why (connect to the consistency-unit / aggregate discussion in Foundations Chapter 3, shared by both tracks, and — on the Laravel track — its domain-modeling chapter).
- Your axis's central tension — see the per-axis hints below.
- Reliability measures — wherever Build B introduced something that can fail in a way Build A couldn't (a network, a vendor, a model, a second store): the timeouts, retries, idempotency, fallbacks, or reconciliation you added (Foundations Chapter 4).
- The surprise — wherever one build turned out much harder (or unexpectedly easier) than the other, document the trade-off you discovered by building.
Then add the signature ADRs for your axis:
| Axis | Signature ADRs to write |
|---|---|
| Build vs. buy | The anti-corruption layer / adapter shape around the vendor; the fallback when the vendor is down or rate-limited; the lock-in / reversibility position (how you'd switch providers). |
| Decomposition | Module vs. service boundaries and data ownership; how the resolve stays consistent without a single-database transaction (saga? eventual?); the BFF-vs-direct-calls decision for the UI in Build B. |
| Consistency | What is the strong-consistency unit vs. what is allowed to be eventual; the compensation/reconciliation strategy when a step fails; what the UI shows during the convergence window. |
| Sync vs. async control flow | Where the workflow state and coordination live; how a mid-workflow failure is handled (orchestrator retry vs. each listener's own reliability); how you'd add a new reaction in each model. |
| Deterministic vs. AI | The model-as-dependency contract (timeout, cost/latency budget, deterministic fallback); how the model's output is constrained and validated at the boundary; the evals approach that replaces exact-match tests; the data/privacy decision for what you send the model. |
| Data store strategy | Why the second store earns its place; how the two stores stay in sync (and the consistency window that opens); which side is the source of truth. |
Part 3 — Trade-off Review
The central deliverable. Compare the two builds, from your actual experience building them — not the textbook answer. End with a defended recommendation.
Your axis's central tension
State, in a paragraph, the one decision this whole capstone was about, and the core tension you felt building both sides of it.
...
Comparison across the dimensions
Use the synthesis chapter's dimensions as a lens. For each one relevant to your axis, note what each build bought and cost in your lived experience (skip the ones your axis didn't really touch).
Boundaries
- Build A:
Where did the seam sit, and how clean was it to enforce?
- Build B:
What did the new boundary buy (isolation? independence?) and cost (a network, a vendor contract, a sync, a fallback)?
Rendering / client-server boundary (if your axis touched the UI's relationship to the backend)
- Build A:
...
- Build B:
...
Transactions / consistency
- Build A:
...
- Build B:
How much harder was correctness once a single transaction wasn't enough? What did compensation/reconciliation cost in code and reasoning?
Async / control flow
- Build A:
...
- Build B:
...
Testing
- Build A:
...
- Build B:
Did testing get harder across the new seam? Did you need contract tests, fakes, or (Axis 5) evals you didn't need in A?
Operations
- Build A:
One thing to run and observe.
- Build B:
What did the alternative cost operationally — a vendor's health, a second store, more deployables, model calls to monitor?
Where each build genuinely helped, and where it was pure overhead
The honest part. Where was Build A blessedly simple? Where did Build B's extra machinery actually help — and where was it complexity you'd never accept in a real project at this scale?
Recommendation
For a realistic version of this product — a real team, real scale, real constraints you should state — which build would you actually ship, and why? Name the costs of your choice as clearly as its benefits. If your answer is "Build A, and I'd move to Build B only if [specific evidence-backed pressure] appeared," state exactly what that pressure would be and what you'd change first.
State your assumptions (team size, scale, constraints):
...
Recommendation:
...
Why this and not the other (the trade-off, with costs named):
...
What would change my mind (the evidence that would make the other build correct):
...
Self-check before submitting
- [ ] I chose an axis I had genuinely low exposure to — I stretched into a decision I hadn't made before.
- [ ] The two builds are genuinely different along my axis, and the difference is visible in the working code.
- [ ] Every ADR's consequences section names real costs, not just benefits.
- [ ] The trade-off review reflects what I actually experienced building both, not textbook recitation.
- [ ] The recommendation is defended by the situation (stated assumptions), not by the appeal of an approach.
- [ ] I stated what would change my mind — proving the recommendation is a reasoned trade-off, not a preference.
If you can tick all six honestly, you've shown the competency the course certifies: not that you picked the "right" build, but that you reasoned the trade-off, named its costs, and wrote down why — the move that holds at any scale, in any stack, on any decision.