mufassall

Cheat sheet · Whole systems

From requirements to design

13 min · Beginner · mufassall.dtwin.uz/en/l/hld-lld/

← Open the lesson

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
Final scene
35%40%60%

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 down

Mermaid: 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 OK

D2

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_db

PlantUML: 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
@enduml

PlantUML: 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
@enduml

Recap

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

MetricStartEnd
Positions in80/s80/s
Rider requests3 000/s3 000/s
Answer p95900 ms180 ms
ETA age12 s60 s

Steps

  1. Problem "Build a bus arrival board"

    The task is one sentence.

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

  3. Case Rough numbers before any boxes

    800 buses, one position every 10 s: 80 writes per second.

  4. Fix High-level design: two paths

    The picture now has two separate paths.

  5. Problem The worker falls behind

    At rush hour one worker computes arrival times for every position.

  6. Fix More workers, one per partition

    The worker group grows to four instances, and the 12 partitions are split between them.

  7. Fix Low-level design: the arrivals API

    Now one component in detail.

  8. Fix Low-level design: one key per stop

    The cache holds one hash per stop: route to seconds of arrival, plus the computation time.

  9. Fix Low-level design: the history table

    History is append-only: one row per position, never updated.

  10. Case Trade-off: stale but available

    The cache goes down.

  11. Recap Recap

    A design is a chain of decisions, each tied to a number.