The One-Page Design Doc: The Format You Will Reuse

Why this matters

Talking lets you skip decisions; writing does not. You can narrate a design for twenty minutes without ever committing to a number, and you will not notice, because speech moves fast enough to hide the gaps. The moment you have to write a line that says peak read rps, you either have a figure or you have an obvious blank, and blanks are the useful output of this exercise. The one-page limit is not a stylistic preference either — it is the mechanism. A page is roughly nine sections of three lines each, which is not enough room for decoration, so every component you keep has to earn its place against something you cut. The format below is the one you will fill in for all ten domain modules of this course, which means that by the end you will have written it ten times and it will have become the way you think rather than a template you consult. It also happens to be the artefact that makes design reviews at work short, because a reviewer can disagree with a specific line instead of with a vibe.

Demo

Nine sections. The rule for each one is stricter than it looks.

1. Purpose — one sentence, naming the user and the job. If it takes two sentences, your scope is still too wide.

2. Scope — three features in, everything else explicitly out. Writing the out list is not padding; it is the part that stops the conversation sprawling.

3. Numbers — DAU, read rps, write rps, bytes per day, retention. Every number derived from a stated assumption, so a reader can disagree with the assumption rather than with you.

4. Targets — p99 latency on the read and write paths separately, availability, durability as RPO and RTO, and which consistency guarantee applies where.

5. Constraints — residency, retention and deletion, budget, team size. The lines that come from outside engineering and delete architectures.

6. Design — one paragraph of prose, then a component list where every entry has exactly one sentence: the property it buys and the cost it charges. No sentence, no component.

7. Data model and invariants — the two or three tables that matter, and the statements that must never be false. The invariants are the most durable thing in the document.

8. The six pressures — one line each. What breaks first, what you change. Not a plan; a demonstration that you have looked.

9. What does not change at 100x — at least three things, each labelled contract, algorithm or deployment, with the reason it survives. This is the section that proves you understand the design rather than having drawn it.

The template and a filled example are below. The filled one is a real URL shortener and it genuinely fits on a page, which is the point: the discipline is in what is absent.

# <system> — one-page design

**1. Purpose.** One sentence: who, and what job.

**2. Scope.** In: A, B, C. Out: everything else, named.

**3. Numbers.**
| metric | value | from |
|---|---|---|
| DAU | | assumption |
| read rps (avg / peak) | | DAU x sessions x reads |
| write rps (avg / peak) | | DAU x rate |
| bytes/day | | writes x object size |
| retention | | constraint |

**4. Targets.** read p99 __ ms · write p99 __ ms · availability __ ·
RPO __ · RTO __ · consistency: <which guarantee, where>

**5. Constraints.** residency · retention + deletion · budget · team

**6. Design.** One paragraph, then:
- component — buys X, costs Y
- component — buys X, costs Y

**7. Data model + invariants.**
- tables/collections that matter
- INVARIANT: <statement that must never be false>

**8. Six pressures.** One line each:
- 100x traffic: breaks __ ; change __
- region down: breaks __ ; change __
- no duplicates: breaks __ ; change __
- reads under 100 ms: breaks __ ; change __
- data stays in country: breaks __ ; change __
- flaky dependency: breaks __ ; change __

**9. What does NOT change at 100x.**
- [contract] __ because __
- [algorithm] __ because __
- [deployment] __ because __

**Open questions.** The two things you would measure first.

Try it yourself

1. Fill the template for a system you can describe in one sentence, and time yourself. First attempt is usually 40 minutes; the tenth is under 10. Note which section took longest — that is your weak spot for the rest of the course.
2. Take the filled URL shortener and delete section 9 entirely, then hand the rest to someone and ask them what the design assumes. They will not be able to tell you, which is the argument for section 9 existing.
3. Check every number in your section 3 against the arithmetic in section 3's from column. Any number without a derivation is a guess wearing a table cell — either derive it or mark it explicitly as an assumption.
4. Go through your section 6 and delete every component whose one sentence you had to strain to write. Count how many survive; a first honest pass usually removes two or three.
5. Print your page. If it runs past one side of A4 at 11pt, cut until it fits without dropping a section — the cutting is the exercise, not the formatting.

References

• Design docs at Google (Malte Ubl)
• RFC 2119 — key words for requirement levels
• The Amazon Builders Library
• Designing Data-Intensive Applications (Kleppmann)