System Design Lab

An interactive system design curriculum. Every topic pairs a written explanation with a live simulation you can push until it breaks — adjust the request rate and watch a fleet saturate, cut a network link and watch a cluster choose between stale answers and no answers, skew a key distribution and watch one shard take the whole load.

Client-side only. No backend, no accounts; progress lives in localStorage.

Stack

Next.js (App Router) · TypeScript · Tailwind CSS v4. Statically exported pages, one accent colour, light and dark themes.

Running it

npm install
npm run dev      # http://localhost:3000
npm run build    # prerenders every topic
npx eslint .
npx tsc --noEmit

Curriculum

Fifteen topics across four modules, following the roadmap.sh System Design roadmap.

Module	Topics	Interactives
1 · Foundations	Scalability vs Performance, Latency vs Throughput, CAP Theorem, Consistency Patterns, Availability Patterns	Scale, Pipe, Partition, Replication, Uptime
2 · Networking	DNS, CDN, Load Balancing	Resolver, Edge, Balancer
3 · Scaling	Horizontal Scaling, Microservices, Service Discovery	Fleet, Blast Radius, Registry
4 · Databases	SQL vs NoSQL, Replication, Sharding, Federation	Query Cost, Topology, Shard, Split

Modules 5–8 (Caching, Asynchronism, APIs, Cloud Design Patterns) are scoped on the home page but not built. They follow the same pattern, so adding one means adding a topic component and registering it.

How it is put together

src/
  lib/
    curriculum.ts   module and topic metadata — the single source of truth
    sim.ts          seeded RNG, fixed-timestep ticker, rolling percentiles
    progress.ts     localStorage-backed completion store
  components/
    Lab.tsx         the shell every interactive sits in
    prose.tsx       Analogy, Tradeoffs, Pitfall, Takeaways
    sims/           one file per interactive, plus shared drawing primitives
    topics/         one file per topic: prose + its lab, registered in index.ts
  app/
    topics/[slug]/  prerendered from the curriculum

Adding a topic

1. Add it to the right module in src/lib/curriculum.ts.
2. Write the simulation in src/components/sims/.
3. Write the page in src/components/topics/<slug>.tsx, default-exporting a component that renders the prose and the lab.
4. Register the slug in src/components/topics/index.ts.

generateStaticParams iterates the curriculum, so a topic listed without a registered component fails the build rather than 404-ing in production.

Why the simulations look the way they do

Each interactive keeps a mutable model in a ref, advances it in place from a requestAnimationFrame loop, and re-renders to draw it. Randomness comes from a seeded generator (Rng in src/lib/sim.ts) rather than Math.random, so a simulation behaves identically on every machine and a stated number — a hit rate, a p99, an availability figure — means the same thing to every reader.

Because that is deliberately not a pure-render pattern, the React Compiler lint rules react-hooks/refs and react-hooks/immutability are disabled for src/components/sims/** and src/lib/sim.ts only. The reasoning is recorded in eslint.config.mjs.

Simulations respect prefers-reduced-motion: the loop falls back to a coarse timer so state still advances without continuous animation.

Progress tracking

Completion is explicit — each topic has a Mark complete button. Nothing is inferred from scrolling or from interacting with a lab. State is a single localStorage key, validated against the current curriculum on read, so renaming a slug drops its stale completion rather than inflating the count.