system-design

System Design (end-to-end, right-sized)

A system is a set of components connected by an unreliable network, each of which can fail, saturate, or fall behind. Good design is not about knowing the fanciest technique — it is about choosing the minimum set of moving parts that meets the requirements at the expected scale, with a clear upgrade path when scale changes. Over-engineering (sharding a table with 10k rows, a Kafka cluster for 5 events/day) is a bug. Under-engineering (a single box with no replica holding the only copy of the data) is also a bug. This skill produces the design in between: the best system needed at that time.

The two modes

Design mode — the user is building something new (or a new subsystem). Run the design method below top to bottom and produce a design doc.

Review mode — the user has an architecture (in code, a diagram, or their head) and wants it audited for scale, reliability, cost, or a specific symptom ("will this survive launch?", "why is this slow?"). Map their current design onto the building blocks, find the missing or oversized pieces, and produce a prioritized findings list. Ground every finding in their actual system.

Scope to what was asked. A full greenfield design runs every step; "should this be a queue?" runs just the relevant building block plus the right-sizing check.

The design method — run in this order

Never jump to a diagram. The order matters: each step constrains the next, and skipping estimation is how people end up sharding a database that fits on one laptop.

1. Scope & requirements. Pin down functional requirements (what it does), non-functional requirements (scale, latency, availability, consistency, durability, cost), and explicit out-of-scope. Ask for the numbers that drive everything: DAU, read:write ratio, payload size, retention, growth. If the user doesn't know, state the assumption you're designing to.
2. Back-of-envelope estimation. Turn the numbers into QPS, peak QPS, storage/year, bandwidth, and memory-for-cache. These decide whether you need one box or one thousand. Cheat-sheet and worked examples in references/design-method.md.
3. API / interface. Define the handful of operations (endpoints, message types, or method signatures) at the system boundary. This forces agreement on what the system actually promises.
4. Data model & storage choice. Entities, relationships, access patterns → then pick the store (SQL vs the four NoSQL families) from the access patterns, not from fashion. Capture the model as an Eraser ERD (references/diagramming-eraser.md). See references/data-and-consistency.md.
5. High-level design. Draw the boxes: clients → LB → stateless service tier → data tier, plus the async paths. Render this as an Eraser cloud-architecture diagram — see references/diagramming-eraser.md. Keep both the picture and the system the simplest thing that satisfies steps 1–4.
6. Deep-dive the hard parts. Every system has 1–3 components that carry the real difficulty (the fanout for a feed, the transcoding DAG for video, the trie for autocomplete, the quorum for a KV store). Design those in detail; the rest is plumbing. For a tricky ordering (fanout, quorum write, auth handshake), add an Eraser sequence diagram of the flow.
7. Identify bottlenecks & scale. Walk the scaling playbook (references/scaling-playbook.md): where is the single point of failure, the hot key, the tier that can't scale horizontally? Add caching, replication, sharding, queues, CDN — only where a bottleneck actually exists.
8. Trade-offs & wrap-up. State what you optimized for and what you gave up, the failure modes and how the system degrades, and the concrete next scaling step when load 10×'s.