Cheat sheet · Whole systems
From requirements to design
The problem
How to approach a design task without jumping to boxes. One small system, a city bus arrival board, goes through requirements, rough numbers, a high-level picture and then a detailed design of one part, with the trade-offs written down.
What you learn
- Functional and non-functional requirements, and why the second kind shapes the design
- Back-of-the-envelope estimates: reads, writes and storage from a few known numbers
- High-level design: boxes, arrows and the two paths of the system
- Low-level design of one component: API, data layout, schema, and a written trade-off
Diagram as code
The lesson's final design as text: paste it into Jira, GitLab, GitHub, Notion or your docs, where Mermaid renders by itself. There are D2 and PlantUML (Confluence, IntelliJ) versions too.
Mermaid: flowchart
flowchart LR
n_rider(["Rider app"])
n_bus(["Bus GPS unit"])
n_api["Arrivals API"]
n_db[("Database")]
n_ingest["Ingest service"]
n_queue[["Position stream"]]
n_worker("ETA workers")
n_cache{{"ETA cache"}}
n_bus --> n_ingest
n_rider --> n_api
n_ingest --> n_queue
n_queue --> n_worker
n_worker --> n_cache
n_worker --> n_db
n_api --x n_cache
n_api --> n_db
classDef down fill:#fde2e2,stroke:#c62828,color:#4a0d0d,stroke-dasharray:4 3
class n_cache downMermaid: request sequence
sequenceDiagram
participant n_bus as Bus GPS unit
participant n_api as Arrivals API
participant n_rider as Rider app
participant n_ingest as Ingest service
participant n_queue as Position stream
participant n_worker as ETA workers
participant n_cache as ETA cache
participant n_db as Database
Note over n_bus,n_api: #34;Build a bus arrival board#34;
n_bus->>n_api: POST /positions HTTP/1.1
n_api-->>n_bus: HTTP/1.1 204 No Content
Note over n_rider,n_api: Requirements: what it does, and how well
n_rider->>n_api: GET /stops/s_204/arrivals HTTP/1.1
n_api-->>n_rider: HTTP/1.1 200 OK
Note over n_ingest,n_queue: High-level design: two paths
n_ingest->>n_queue: topic bus-positions, key b_17, partition 3
Note over n_queue,n_worker: The worker falls behind
n_queue->>n_worker: consumer group eta-workers
Note over n_rider,n_api: Low-level design: the arrivals API
n_rider->>n_api: GET /v1/stops/s_204/arrivals HTTP/1.1
n_api-->>n_rider: HTTP/1.1 200 OK
Note over n_worker,n_cache: Low-level design: one key per stop
n_worker->>n_cache: HSET arrivals:s_204 R11 240 R3 610 updated_at 1795421720
n_cache-->>n_worker: (integer) 3
Note over n_worker,n_db: Low-level design: the history table
n_worker->>n_db: INSERT INTO positions (bus_id, route, ts, lat, lon)
n_db-->>n_worker: INSERT 0 1
Note over n_rider,n_api: Trade-off: stale but available
n_rider->>n_api: GET /v1/stops/s_204/arrivals HTTP/1.1
n_api-->>n_rider: HTTP/1.1 200 OKD2
direction: right
n_rider: "Rider app" {
shape: rectangle
}
n_bus: "Bus GPS unit" {
shape: rectangle
}
n_api: "Arrivals API" {
shape: rectangle
}
n_db: "Database" {
shape: cylinder
}
n_ingest: "Ingest service" {
shape: rectangle
}
n_queue: "Position stream" {
shape: queue
}
n_worker: "ETA workers" {
shape: rectangle
style.multiple: true
}
n_cache: "ETA cache" {
shape: hexagon
style.fill: "#fde2e2"
style.stroke: "#c62828"
style.stroke-dash: 3
}
n_bus -> n_ingest
n_rider -> n_api
n_ingest -> n_queue
n_queue -> n_worker
n_worker -> n_cache
n_worker -> n_db
n_api -> n_cache {
target-arrowhead.shape: cross
}
n_api -> n_dbPlantUML: request sequence
@startuml
participant "Bus GPS unit" as n_bus
participant "Arrivals API" as n_api
participant "Rider app" as n_rider
participant "Ingest service" as n_ingest
queue "Position stream" as n_queue
participant "ETA workers" as n_worker
collections "ETA cache" as n_cache
database "Database" as n_db
note over n_bus, n_api : "Build a bus arrival board"
n_bus -> n_api : POST /positions HTTP/1.1
n_api --> n_bus : HTTP/1.1 204 No Content
note over n_rider, n_api : Requirements: what it does, and how well
n_rider -> n_api : GET /stops/s_204/arrivals HTTP/1.1
n_api --> n_rider : HTTP/1.1 200 OK
note over n_ingest, n_queue : High-level design: two paths
n_ingest -> n_queue : topic bus-positions, key b_17, partition 3
note over n_queue, n_worker : The worker falls behind
n_queue -> n_worker : [retry] consumer group eta-workers
note over n_rider, n_api : Low-level design: the arrivals API
n_rider -> n_api : GET /v1/stops/s_204/arrivals HTTP/1.1
n_api --> n_rider : HTTP/1.1 200 OK
note over n_worker, n_cache : Low-level design: one key per stop
n_worker -> n_cache : HSET arrivals:s_204 R11 240 R3 610 updated_at 1795421720
n_cache --> n_worker : (integer) 3
note over n_worker, n_db : Low-level design: the history table
n_worker -> n_db : INSERT INTO positions (bus_id, route, ts, lat, lon)
n_db --> n_worker : INSERT 0 1
note over n_rider, n_api : Trade-off: stale but available
n_rider -> n_api : GET /v1/stops/s_204/arrivals HTTP/1.1
n_api --> n_rider : HTTP/1.1 200 OK
@endumlPlantUML: components
@startuml
left to right direction
agent "Rider app" as n_rider
agent "Bus GPS unit" as n_bus
component "Arrivals API" as n_api
database "Database" as n_db
component "Ingest service" as n_ingest
queue "Position stream" as n_queue
collections "ETA workers" as n_worker
stack "ETA cache" as n_cache #fde2e2;line:c62828;line.dashed
n_bus --> n_ingest
n_rider --> n_api
n_ingest --> n_queue
n_queue --> n_worker
n_worker --> n_cache
n_worker --> n_db
n_api -[#c62828]-> n_cache
n_api --> n_db
@endumlRecap
A design is a chain of decisions, each tied to a number.
1) Write functional and non-functional requirements first: the second kind decides the design. 2) Estimate reads, writes and storage to find the heavy part. 3) High level: boxes and arrows, separate paths for different loads. 4) Low level for one component at a time: API, data layout, schema. 5) Write down each trade-off and the requirement behind it.
Numbers: at the start and at the end
| Metric | Start | End |
|---|---|---|
| Positions in | 80/s | 80/s |
| Rider requests | 3 000/s | 3 000/s |
| Answer p95 | 900 ms | 180 ms |
| ETA age | 12 s | 60 s |
Steps
- Problem "Build a bus arrival board"
The task is one sentence.
- Fix Requirements: what it does, and how well
Functional: a bus reports its position every 10 seconds; a rider opens a stop and sees the next buses with minutes to arrival.
- Case Rough numbers before any boxes
800 buses, one position every 10 s: 80 writes per second.
- Fix High-level design: two paths
The picture now has two separate paths.
- Problem The worker falls behind
At rush hour one worker computes arrival times for every position.
- Fix More workers, one per partition
The worker group grows to four instances, and the 12 partitions are split between them.
- Fix Low-level design: the arrivals API
Now one component in detail.
- Fix Low-level design: one key per stop
The cache holds one hash per stop: route to seconds of arrival, plus the computation time.
- Fix Low-level design: the history table
History is append-only: one row per position, never updated.
- Case Trade-off: stale but available
The cache goes down.
- Recap Recap
A design is a chain of decisions, each tied to a number.