Skip to main content

The Capstone Design Doc: Structure, Length, Audience

What This Concept Is​

The capstone design doc is the one document that replaces every other document your capstone might produce. It is the single source of truth -- the place where problem, characteristics, domain model, architectural style, diagrams, ADR index, fitness functions, MVP, risks, and schedule all live side by side so that drift between any two is visible. It is written once in week 1 and edited (not rewritten) in weeks 2-5.

Length: 4 to 8 pages. Fewer is missing something. More is padding.

Audience: the grader, and you in week 5 at 11pm. Both need to read fast and act on the content, not admire the prose.

Structure (non-negotiable order):

  1. TL;DR (3-5 sentences): what the capstone is, for whom, what it proves.
  2. Top-3 characteristics (a list): the lens for every subsequent decision.
  3. Problem statement + "why this?" (one paragraph each).
  4. Glossary (ubiquitous language, 10-20 terms).
  5. Domain model (subdomain map + bounded contexts; which is core).
  6. Architecture (chosen style with three-alternatives table).
  7. C4 diagrams (Context, Container, Component).
  8. ADR index (links to the three ADRs).
  9. Fitness functions (one line per: what it asserts, where it runs).
  10. MVP (user, trigger, steps, success, non-goals).
  11. Risks (top 5 from the risk register).
  12. Schedule and scope-cut rules (week-by-week plan; pre-committed cuts).

Why It Matters Here (In the Capstone)​

A design doc of this shape is the spine of the capstone. Every ADR links back to it. Every fitness function references a line from it. The diagrams are embedded in it. The defense (concept 15) is delivered from it. Removing any section removes a load-bearing joint: skip fitness functions and drivers become wall art; skip non-goals and scope silently inflates; skip glossary and the diagrams drift from the code.

Why one doc and not many? At capstone scale, fragmented docs drift. With one doc, drift is visible: if the diagram disagrees with the text, one of them is wrong and you can see the contradiction on the same page. A grader can cold-read the doc in ten minutes and walk you through the system back; that is the operational test of a design doc worth reviewing.

The third reason: the doc is the artifact you will most reuse professionally. Real engineering teams run on written-first culture -- design docs, RFCs, memos. The capstone design doc is your earliest, most visible demonstration that you can communicate in the shape the rest of your career will demand.

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

Example A -- inventory service, skeleton:

# Inventory Capstone Design Doc

## TL;DR
Scan-and-reconcile inventory service for a single-warehouse shop (2-4 staff).
Offline-capable scan path with idempotent server-side merge. Modular monolith.
MVP: receive a SKU, scan offline, sync, correct on-hand.

## Top-3 Characteristics
1. Correctness under concurrency and offline   2. Operability   3. Offline scan availability

## Problem / "Why this?"
[one paragraph each -- see concept 01]

## Glossary
- ScanEvent: immutable scan record. Fields: scanId, sku, qtyDelta, ...
- OnHand: derived quantity. Never directly mutated.

## Domain Model
Core: scan lifecycle. Supporting: reconciliation, persistence. Generic: logs, auth (skipped for MVP).

## Architecture
Chosen: modular monolith. Alternatives: monolith, services. [table]

## Diagrams
[C4 Context] [C4 Container] [C4 Component of scan-core]

## ADRs
- ADR-001: Modular monolith as style
- ADR-002: Postgres as store with append-only scan_event table
- ADR-003: Single region, managed Postgres

## Fitness Functions
- arch/module-boundaries: no cross-module internal imports
- correctness/idempotency: same-key scan replayed yields zero drift
- ci/health-check: curl /health post-deploy

## MVP / Risks / Schedule
[MVP 5-part] [top 5 risks] [6-week plan + cut rules]

Example B -- ticketing platform, TL;DR and fitness sections:

TL;DR. Student-club event ticketing platform with strict seat-cap enforcement, QR issuance, and offline-capable door scanning. Modular monolith backed by Postgres. MVP proves no oversell under concurrent buys, QR round-trips correctly, and the door-scan works for a 200-person event.

Fitness Functions. (1) no-oversell -- 100 concurrent buyers on a 1-seat tier produce exactly 1 success; (2) scan-uniqueness -- a QR scanned twice returns "already used"; (3) deploy health -- /health returns 200 after every deploy.

Example C -- finance aggregator, risks and non-goals:

Risks. (1) silent dupe import -- mitigated by contentHash + staging table; (2) rules engine complexity -- mitigated by YAML + table-driven tests; (3) data on a lost laptop -- mitigated by passphrase-derived encryption at rest.

MVP non-goals. No cloud sync, no bank API, no multi-user, no web-accessible storage. These are non-goals driven by the Privacy driver (#2).

Each doc is 4-8 pages formatted, under 1 page per section. A grader reads it once, explains the system back, and asks the three probing questions from concept 15 -- and the doc supplies the answers.

Common Confusion / Misconceptions​

  • "The design doc is where I put all my thoughts." It is where you put your decisions. Thoughts belong in a scratchpad. A design doc with 20 pages of "considerations" is unreadable and therefore useless.
  • "Design doc should have a 'future work' section." Strictly optional and at capstone scale almost always a trap -- speculative features go there to die. If it appears, limit it to one paragraph and treat it as "things I learned I do not need."
  • "Write the doc after the code." A post-hoc design doc is memoir, not engineering. The decisions were never visible when they could be challenged, so the doc is worth almost nothing.
  • "The doc and the README are the same thing." No. The README is "how to run this." The design doc is "why this system is the way it is." Different audiences, different lifetimes.

How To Use It (In Your Capstone)​

  1. Create the 12-section skeleton on day 1. Empty headings are fine; a TODO is acceptable; nothing is not.
  2. Fill each section as the corresponding concept is worked. Characteristics in after concept 07. C4 after concept 11. ADRs links after concept 12. Risks after concept 02.
  3. Do not reorder sections. Fixed structure so any reader knows where to find anything.
  4. Edit during weeks 2-5 only when a decision changes -- not to polish prose.
  5. Do a "read it cold" pass on day 5 of week 1. If any section confuses you 48 hours later, it will confuse the grader. Rewrite.
  6. Never paste a URL into the doc that hasn't been explained in one sentence. The doc must stand alone.
  7. At the end of each week, reconcile the doc with reality. If the code has modular-monolith boundaries but the doc still says "modular monolith planned," the doc is stale. Fix.

See also (integrative)​

The capstone design doc is a compressed, one-person version of the written-first culture S8 M05 teaches and the S8 M01 design-doc pattern. It also carries the communicate-the-architecture discipline from S7 M01.

External references (curation-validated this session):

Check Yourself​

  1. How many pages should your design doc be, and why that range?
  2. Who is the reader, and what do they need from the doc?
  3. Name two sections commonly missing from student capstone design docs (non-goals, fitness functions, scope-cut rules are the top three candidates).
  4. Does every section of your doc reference at least one concrete artifact (an ADR, a diagram, a test, a file path)?
  5. If you ran a 10-minute cold read with a peer, could they explain the system back without prompting?

Mini Drill or Application (Capstone-scoped)​

  • Drill 1 (30 min). Create the 12-section skeleton in library/raw/design-doc.md. Fill sections you already have answers for (problem, risks, MVP from Cluster 1; domain model and glossary from Cluster 2). Leave the rest with TODO.
  • Drill 2 (20 min). Day 5 cold read. Open the doc after a 48-hour gap. For every section, ask: "does this say a decision, or a hope?" Rewrite the hopes into decisions or demote to non-goals.
  • Drill 3 (15 min, weekly). Friday reconciliation: for each section, check whether the code still matches. Mark any drift.
  • Drill 4 (10 min, once, week 3). Pass the doc to a peer (or imagine the grader). Collect "what do you mean by X?" questions. Those are the sentences to rewrite tomorrow.
  • Drill 5 (25 min, week 5). Rehearse the 5-minute defense (concept 15) from the design doc only. If you need to pull up the code or the README, the doc is incomplete.

Source Backbone​

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