Platform Engineering · Lesson 163

Service Design from Scratch: Requirements, NFRs, and the Design Brief

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

Run it as:

When it breaks, I check

One thing to remember

Where the time goes

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.

Try it: turn an ask into numbers

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).

50,000,000reads / day
~579average reads / s
~5,787peak reads / s
8app pods needed
16,000,000scans / day
~1.8 TBevent storage / year

Six deployed pods are short for the peak

Check yourself

Three questions. No score is saved anywhere — this is just you against the material.

Basic to master

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.

Basic — The ask, the problem, and the verbs

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:

  • Functional requirements: what the system does, one actor and one verb each.
  • Actors: every person or system that reads or writes, including machines like the courier app.
  • The success measure: the number that improves if this ships.

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".

Intermediate — NFRs that can fail a test

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:

  • Latency, as a percentile: p50 tells you the typical user, p99 tells you the unhappy one.
  • Availability, as a success ratio over a window, which becomes the SLO later.
  • Freshness and consistency: how stale may an answer be, and may two readers disagree.
  • Durability, security, privacy, cost ceiling, and compliance constraints.

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.

Advanced — Estimates, peaks, and the trade-off table

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:

  • Load estimates: requests per second, average and peak, reads versus writes.
  • Data estimates: rows per day, bytes per row, retention, so storage per year.
  • Trade-offs: freshness against cost, consistency against availability, latency against durability.
  • Invariants: rules about data that must never break, listed in their own section.

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.

Master — Requirements as a contract that keeps changing

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:

  • SLOs derived from NFRs, with an error budget and a policy for when it runs out.
  • Requirement traceability: each requirement links to the design section, the test, and the dashboard that proves it.
  • Change control: a requirement changes through a short written decision, not a chat message.
  • Cross-team contracts: the courier app team and the tracking team agree on scan semantics in writing.

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.

Go deeper

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.

Check the brief like code

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.

One time it broke

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.

Timeline

  • Day 1Support flags a handful of complaints. The parcels show delivered in the courier system and out for delivery on the page.
  • Day 2The cache is suspected and flushed. The wrong statuses come back within the hour.
  • Day 3The scan log shows the pattern: vans in poor signal areas upload a batch of scans when they reach coverage, and the batch arrives in random order. The last message written wins.
  • Day 3, eveningThe write path changes to keep the furthest status in the lifecycle, and to log any scan that would move status backwards.
  • Day 4A backfill recomputes current status from the full scan history. About 9,000 parcels are corrected.

What changed after

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.

If you remember nothing else

Design exercise

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.

Clarifying questions to ask

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?

Rough sizing

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.

Shape of the answer

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.

Trade-offs to name

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.

Saved on this device, in this browser.
Next in this series · Lesson 164
High-Level Design in Depth: Components, Boundaries, and Data Flow

The brief from the last lesson says what the parcel-tracking service must do, how fast, and how big. The high-level design says what it is made of: which components exist, what each one owns, which arrows are synchronous and…

Go to Lesson 164 →

Or browse the full course from the Lessons index.