Hands-On Builds — Fifteen Lego-Block Pages

One page per project. Each builds the project's machinery out of numbered, independently runnable blocks — a block is a lego piece that constructs one mechanism, proves it works on its own, and hands what it made to the next one — and then an assembly that wires every block into a single working system and measures it.

These are not summaries of the project pages. They are the executable core of each project, small enough to run in seconds and complete enough that the assembly does something real: a transformer that trains to 0.11 nats, a Raft cluster that elects exactly one leader under partition, a recommender that measures why three of its four models lose to a bincount, an autodiff engine that matches PyTorch to 5.6e-17 over 300 optimisation steps.

Every number on every page was produced by running the code. The pages are generated by handson/build_pages.py, which slices the code out of each script and captures that script's real output. Nothing is transcribed by hand, so a result that drifts cannot silently stay stale on the page — regenerating rewrites it.

Where a measurement contradicted what I expected, the contradiction stayed in. Six of these pages document a wrong prediction and the experiment that corrected it, because that sequence is the thing the track is actually teaching.

Each page also carries a deep-dive section written for someone who already knows the mechanism: the design space with alternatives, the latency and memory-hierarchy arithmetic that constrains it, what changes on GPU/TPU/SSD/HDD, the advanced algorithms the toy version stands in for, how the project connects to the other fourteen, the failure modes at scale, and the primary sources. The Concept Map collects the eight mechanisms that recur across all fifteen projects and shows where each one appears.

Contents

109 blocks, 4,260 lines of runnable Python, 356 KB of generated pages.

Running them

cd handson
python3 h01_transformer.py            # every block, then the assembly
python3 h08_recsys.py --block 5       # one block and its prerequisites
python3 h14_hardware.py --quiet       # the assembly only
python3 build_pages.py                # regenerate all fifteen pages
python3 build_pages.py h04            # regenerate one

Only numpy is required. Three pages use torch if it is installed, to check their own results against a reference implementation, and skip that check cleanly if it is not.

The cross-cutting view

The Concept Map is the companion to these pages. Fifteen projects share far fewer than fifteen mechanisms — an approximate test guarding an exact one, an atomic pointer swap for durability, the memory hierarchy as the cost model, the arithmetic of maxima, two-stage retrieval, restriction as the enabler of recovery, the accuracy/latency dial, and amortising a fixed cost. That page indexes every appearance of each.

Where these sit in the track

Walkthroughs are six 40–60 minute miniatures that each end in one surprising finding. These hands-on pages are longer and structured differently: they cover a whole project's mechanisms rather than one idea, and they are meant to be read alongside the project page while you build the real version.

The reading order that works: skim the project page for scope, run the hands-on script to see the mechanisms move, read the hands-on page for what each one costs, then start the real build with the scaffold. The hands-on version is deliberately the smallest thing that demonstrates the mechanism — the project page's milestone list is what turns it into a system.

The self-corrections

Kept deliberately, with the measurement that forced each one:

Each page links back to its full project specification, and every project page links forward to its hands-on build.