System design from the internals up.
The layer below the interview guides: how CPython, storage engines, Kubernetes and
telemetry pipelines actually work, plus labs where you predict, break, and measure.
📖 harut8.github.io/system-design: searchable, dark mode, works on mobile
Most system design material stops at the whiteboard: "put a cache here, shard there."
These notes go one layer down, to the mechanisms that decide whether that box diagram
survives production. Why an UPDATE in Postgres is really an INSERT. What the kubelet does
between kubectl apply and a running container. Where the GIL is actually dropped. Why
your p99 alert pages at 3 a.m. for nothing.
- 220+ chapters across 8 tracks, from CPU caches to RAG evaluation, written from primary sources (papers, source code, RFCs)
- Labs for every track: predict a number, measure it on your laptop with Docker, then break something on purpose
- 21 design problems with full solutions, and reference implementations at four scales (10k → 100k → 1m → 10m)
- Spaced-repetition questions at the end of each lab section (redo after a day, a week, a month)
| If you want to… | Read in this order |
|---|---|
| Prepare for a system design interview | Distributed systems primitives → Replication → Caching → Sharding → then work the design problems |
| Understand databases for real | Mental model → Storage engines → Transactions → LSM trees → WAL |
| Go from Kubernetes user to Kubernetes operator | Linux primitives → etcd → API server → Scheduler → Kubelet |
| Own reliability / on-call | SRE mental models → OpenTelemetry → Alerting → SLO engineering → On-call |
| Run GPU / LLM infrastructure | GPU mental models → DCGM exporter → Utilization efficiency → LLM inference |
| Build RAG that holds up in production | RAG mental models → Chunking → Hybrid retrieval → Evaluation |
| Know what your Python actually does | CPU execution model → Refcounting → Eval loop → The GIL → Free-threading |
| Track | What it covers | Chapters |
|---|---|---|
python-mastery/ |
CPU execution model, caches, virtual memory, allocators, syscalls, then CPython internals: refcounting, eval loop, GC, the GIL, free-threading, asyncio | 30 |
databases/ |
Storage engines, encoding formats, access methods, query engines, transactions, B-trees and LSM-trees, WAL, vector search, data lake and lakehouse | 25 |
distributed-systems/ |
System models and CAP/PACELC, replication and consistency, consensus, sagas/outbox/idempotency, sharding, streaming, resilience and load control, multi-region, production debugging, disaster recovery | 17 |
kubernetes/ |
Linux primitives, etcd, API server, scheduler and kubelet internals, CNI/Cilium/eBPF, CSI, operators, multi-tenancy, supply-chain security | 46 |
k8s-learn/ |
Hands-on Kubernetes task sheets with manifests | 14 |
sre-observability/ |
OpenTelemetry, instrumentation, telemetry storage and query layers, SLO engineering, on-call, cardinality and cost | 47 |
gpu-observability/ |
DCGM internals, GPU cluster telemetry, utilization efficiency, failure detection, LLM inference and training observability | 23 |
ai-rag/ |
Embeddings, chunking, vector indexes, hybrid retrieval and reranking, evaluation methodology, agents and orchestration, plus labs | 21 + labs |
tasks/ · solutions/ |
21 interview-style design problems, Mid to Staff level, each with a full solution and an interview kit | 21 |
implementation/ |
Runnable reference implementations of the same design at 10k, 100k, 1m and 10m scale (FastAPI, Postgres, Redis, Docker Compose) | 4 designs |
primitives/ |
The reusable decisions extracted from the worked solutions, so the next design costs less than the last | — |
SYSTEM-DESIGN-GUIDE.md |
Cross-cutting reference tying the tracks together | — |
Every track has a LABS.md of learn-by-doing tasks, one section per chapter. Each task asks you to
predict a result before measuring it, break something on purpose, and end with a number you can check.
Each section closes with three closed-book questions to redo after a day, a week and a month, and each
sheet ends with multi-day capstones. They run on a laptop with Docker; anything paid is marked optional.
databases · distributed-systems ·
python-mastery · kubernetes (with k8s-learn/ for the API basics) ·
sre-observability · ai-rag · gpu-observability
The notes are plain Markdown and readable straight from the repository. The site build is only needed to preview the published HTML.
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements-docs.txt
./scripts/stage-docs.sh # collect the topic dirs into .docs-build/
mkdocs serve # http://127.0.0.1:8000scripts/stage-docs.sh copies the tracked Markdown into a single tree so
MkDocs has one docs_dir, keeping the relative layout intact so the
cross-links between tracks still resolve. Re-run it after adding or renaming
files. Publishing happens automatically on push to main via
.github/workflows/pages.yml.
Found a wrong number, a broken lab, or an explanation that doesn't land? Open an issue or a pull request. See CONTRIBUTING.md. Fixes with a source (paper, source line, docs link) are merged fastest.
If these notes saved you an afternoon, a ⭐ helps other engineers find them.
The notes are licensed under CC BY-SA 4.0: share and adapt them with attribution,
under the same license. Code (implementation/, ai-rag/labs/, and other source files) is
MIT.