Every service I have designed started as one sentence from someone who did not know it was a design problem. "Customers keep calling to ask where their parcel is. Can we show them?" That sentence is not a design. It is an ask. Between the ask and the first box on a whiteboard sits the part most engineers skip: who uses it, what it must do, how fast, how big, how available, and what we will not build. This lesson walks one request through a parcel-tracking service, and at every hop it shows the requirement that decided how the hop works. By the end you can turn any ask into a one-page design brief that a team can build from and a reviewer can argue with.
Difficulty: Beginner · Know this first: Lesson 19, Lesson 48
Each hop owns a slice of the 300 ms latency budget from NFR1. The bar is a worked example for this lesson, not a measurement from a live system, but the shape is honest: the app tier and the database own most of it, and those are exactly the two hops the estimates size.
Move the sliders and watch the brief's estimates change. These are the numbers from steps 5 to 7. The app-tier hop in the budget bar above follows your peak.
reads/day = parcels × reads per parcel · average reads/s = reads/day ÷ 86,400 · peak reads/s = average × peak ratio
app pods = peak reads/s × 1.3 headroom ÷ 1,000 per pod, rounded up · scans/day = parcels × 8 · event storage/year = scans/day × 365 × 300 bytes
app-tier hop = 40 ms while pods cover the peak; it grows with the shortfall when they do not (six pods are deployed in the worked example).
Six deployed pods are short for the peak
Three questions. No score is saved anywhere — this is just you against the material.
Requirements work looks like one skill. It is four levels, and each fixes the failure that hurt most at the level below: first you learn to separate the ask from the problem, then to write requirements that can fail a test, then to estimate and trade, and finally to run requirements as a living contract across teams.
At the basic level you learn to stop designing the first sentence you hear. The ask is "show customers where their parcel is". The problem is "40,000 support calls a week". The functional requirements are the verbs the system must perform, written as "an actor can do a thing": a customer can read status, a courier can post a scan, an agent can read history.
Types:
Uses: every new service, feature, or migration. The win at this level is that two engineers, reading the same list, would draw the same endpoints.
Where it breaks: a list of FRs with no numbers behind it. It describes a system that works on a laptop with one user, which is not the system anyone needs.
Try it: Basic
Which line is a functional requirement?
Now do it: Pick a service you use daily. Write its three most important functional requirements as "an actor can do a thing".
At the intermediate level every quality gets a number, a percentile, and a window. Latency is p99 under 300 ms over five minutes. Availability is 99.9 percent of requests per month, which is about 43 minutes of failure budget. Freshness is "visible within 60 seconds". Durability is "no acknowledged scan is ever lost".
Types:
Uses: NFRs decide the architecture far more than FRs do. A 60-second freshness budget allows a cache; a "never stale" rule forbids it. A 99.99 percent target needs a second region; 99.9 does not.
Where it breaks: NFRs copied from the last project. A 99.99 target nobody needs costs a second region and an on-call rotation; a missing freshness number starts a two-week argument about caching.
Try it: Intermediate
NFR3 says a scan is visible within 60 seconds. What does that number allow the design to do?
Now do it: Take a service you know and write its latency, availability, and freshness requirements as numbers with a percentile and a window.
At the advanced level the brief carries numbers that size the system: average, peak, and growth. Two million parcels a day at 25 reads each is 580 reads a second on average, 5,800 at a 10x peak, and next year's plan if volume grows 40 percent. Then you trade: you cannot have every NFR at its best at once, so the brief names which one wins when they collide.
Types:
Uses: every box on the HLD traces to one of these numbers. When a reviewer asks "why six pods?", the answer is a line in the brief, not a feeling.
Scale and failure: at 10x growth the numbers that hurt first are the peak read rate and the storage per year; at 100x it is the write rate and the cost line. The failure mode at this level is precision without accuracy: an estimate to four significant figures built on a guessed reads-per-parcel nobody measured. Ask for the real number from logs before you trust the arithmetic.
Try it: Advanced
You have average reads per second and nothing else. What two numbers does the brief still need before anyone sizes the app tier?
Now do it: Use the slider tool above with your own service's numbers and write the peak reads per second and pod count into a brief.
At the master level requirements are a living contract between teams, not a document written once. NFRs become SLOs with owners and error budgets; invariants become checks that run in production; estimates are compared with real traffic every quarter; and every change to a requirement is a recorded decision, because a design built on a requirement that quietly moved is a design nobody can explain.
Types:
Uses: platform services that many teams depend on, regulated systems, and anything that will outlive its first team. The master-level habit is asking "which requirement does this alert protect?" and "which requirement does this cost buy?"
Trade-off: this rigour costs time on every change, so it is applied where the blast radius is large. A one-team internal tool gets a one-page brief; a service the whole company calls gets SLOs, traceability, and change control.
Try it: Master
Six months in, product quietly changes "visible within 60 seconds" to "visible instantly" in a chat thread. What does a master-level team do?
Now do it: For one service you run, link each SLO to the requirement it came from. Any SLO with no requirement, or requirement with no SLO, is the next conversation.
The brief is a template, and the template is most of the value. I use the same nine headings for every service, because the headings are the checklist. An empty heading is a question nobody has asked yet, and an empty heading is much easier to spot than a missing paragraph.
# Design brief: parcel tracking (v1)
Problem: 40,000 where-is-my-parcel calls/week, ~4 min each
Success: calls down 50% within 3 months of launch
Actors: customer (read own status), courier app (write scans),
support agent (read full history)
FRs: FR1 read current status · FR2 post scan · FR3 read history
NFRs: p99 read < 300 ms · 99.9% reads succeed/month
scan visible < 60 s · no acknowledged scan lost
Estimates: 2M parcels/day · 25 reads + 8 scans per parcel
580 reads/s avg · 5,800 peak (10x) · +40%/year
Constraints: only the recipient sees address and window (PII)
Invariants: status only moves forward · one parcel, one current status
Non-goals: live map · change address · notifications
Open: retention for scan history? 90 days or 2 years?Nine headings, one page. The Open line matters as much as the rest: it is the list of things the design is allowed to be wrong about.
A brief can be linted. This script flags the three mistakes I see most: an NFR with no number, an estimate with no peak, and a brief with no invariants or non-goals.
# python3 brief_lint.py
import re
brief = {
"nfrs": ["p99 read < 300 ms", "99.9% reads succeed/month", "tracking is fast"],
"estimates": {"avg_rps": 580},
"invariants": [],
"non_goals": ["live map"],
}
problems = []
for n in brief["nfrs"]:
if not re.search(r"\d", n):
problems.append(f"NFR with no number: {n!r}")
if "peak_rps" not in brief["estimates"]:
problems.append("estimate has an average and no peak")
if not brief["invariants"]:
problems.append("no invariants: what must never be true?")
if not brief["non_goals"]:
problems.append("no non-goals")
print("\n".join(problems) or "brief OK")
Expected: three problems, the vague NFR, the missing peak, and the empty invariants list. Add "peak_rps": 5800 and the invariant "status only moves forward" and run it again; one problem is left, and fixing it is the point of the exercise.
A tracking page I helped build showed "out for delivery" for parcels that had been delivered hours earlier. Not for everyone. For about one parcel in two hundred, mostly in rural areas. Each one became a support call, which was exactly the cost the service existed to remove.
The code fix took an hour. The real change was in the template: every design brief now has an Invariants heading, and a brief with an empty Invariants section does not pass review. The rule "status only moves forward" was obvious to everyone who heard it. It was not written anywhere, so nothing enforced it.
Your company wants a "status page" so customers can see when the product is degraded. Write the one-page design brief: problem, actors, FRs, NFRs, estimates, constraints, invariants, non-goals, and open questions.
Who updates the status, a person or automation, or both? Does the page need to stay up when the main product is down? How many visitors at peak, which is usually during an outage? Are there regions or components shown separately? Is subscription by email in scope?
Say 50,000 customers, and during a big outage 30 percent of them reload the page every minute: about 250 reads a second at peak, against nearly zero on a normal day. Writes are a handful an hour. Storage is tiny. The peak-to-average ratio is the whole design problem.
FRs: a visitor reads current status per component; an operator posts an incident update; automation sets a component degraded from health checks. NFRs: the page stays available when the main product is down, so it runs on separate infrastructure; updates visible within 30 seconds. Invariant: an incident is never shown resolved while a linked component is still marked down. Non-goals: subscriptions and history charts in v1.
Hosting the status page on the same platform as the product is cheaper and fails exactly when it is needed. Static pages behind a CDN survive any peak and make updates slower. Automation updates faster than people but will post false alarms unless it waits for two consecutive failed checks.