# Phase 1 · Module 0 — Orientation > Estimated time: ½ day · Pinned to commit `1aedee4` · Needs no build or model. ## Where this fits An orientation. Before any deep dive into *how* DeepSeek V4 Flash is computed, you need the map: what DS4 is, which file does what, and how the pieces compose into one system. With that map, the code reads as a structure instead of a pile of very large files. This module gives the map only. Each major file gets its own module later; here the goal is just to know what everything *is* and how it connects. ## Read first - [`README.md`](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/README.md) — read the top section ("DwarfStar 4"), "Motivations", and "Native agent". Skim the rest. - [`AGENT.md`](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/AGENT.md) — the project's own statement of goals and layout. Short; read all of it. - [`Makefile`](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/Makefile) — read it top to bottom. It is ~195 lines and it *is* the build's architecture diagram. - Skim the comment block at the very top of [`ds4.h`](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/ds4.h#L9) and [`ds4_gpu.h`](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/ds4_gpu.h#L7). You do not need to understand the functions — just notice each header opens with a paragraph describing a *contract*. ## The DS4 detail ### What DS4 is DS4 is a **single-purpose inference engine** written in C. It runs exactly one model family — DeepSeek V4 Flash — and refuses everything else. It is deliberately *not* a generic model runner like llama.cpp. The bet, in the project's own words, is narrow: take one excellent model and make it feel *finished* end-to-end on high-end personal hardware (Mac Studios, 96–128 GB MacBooks, NVIDIA DGX Spark). "Finished" means three things shipped together: the **engine**, a **GGUF** model file crafted for this engine's exact assumptions, and **validation** against logits from the official DeepSeek implementation. ### The codebase: what each compiled file does This is the part to actually learn. The repo has a handful of large `.c` files; here is what each one *is*. (A `.c` or `.m` file is a unit of C / Objective-C source code.) **The engine — `ds4.c`** (~18,400 lines). The inference engine, and the heart of the project. It memory-maps the GGUF model file, tokenizes text, schedules the forward pass through all 43 model layers, owns *sessions* (a session = one running inference with its own KV cache), and serializes KV snapshots to and from disk. It also contains a CPU reference implementation used to check the GPU path. Its public face — the only part other files are allowed to use — is the header `ds4.h`. **The GPU backend — `ds4_metal.m` or `ds4_cuda.cu`** (one per build): - `ds4_metal.m` (~14,700 lines, Objective-C) plus the 19 kernel files in `metal/` — the Apple GPU backend. It reads the `.metal` kernel source files at startup and compiles them on the fly. - `ds4_cuda.cu` (~10,700 lines, CUDA C++) — the NVIDIA GPU backend, used on Linux including the DGX Spark. Its kernels are compiled at build time by `nvcc`. Both implement the *same* contract (`ds4_gpu.h`), so the engine code does not change between them. A build links exactly one. **The five front-ends** — each is a thin program wrapped around the engine: | Executable | Driver file | What it is | |---|---|---| | `ds4` | `ds4_cli.c` (~1,470 lines) | Command-line tool: one-shot prompts and an interactive REPL chat. The simplest front-end. | | `ds4-server` | `ds4_server.c` (~14,700 lines) | HTTP server, OpenAI/Anthropic-compatible. One inference worker thread, many client threads. | | `ds4-agent` | `ds4_agent.c` (~6,600 lines) | Native coding agent: a two-thread UI + worker program running a tool-calling loop. | | `ds4-bench` | `ds4_bench.c` (~420 lines) | Throughput benchmark: prefill/decode speed at growing context sizes. | | `ds4-eval` | `ds4_eval.c` (~3,300 lines) | Capability eval: 92 embedded hard questions, run and graded, in a terminal UI. | **Three shared helper libraries:** - `ds4_kvstore.c` (~1,280 lines) — the disk KV cache: reads and writes SHA1-named `.kv` checkpoint files. Linked into `ds4-server` and `ds4-agent`. - `rax.c` (~2,750 lines) — a *radix tree* (a compressed prefix-trie data structure), vendored from Redis. Linked only into `ds4-server`, where it indexes tool-call memory. - `linenoise.c` (~2,600 lines) — a line-editing library (a compact `readline` replacement), vendored. Linked into `ds4` and `ds4-agent` for interactive input. **Two contracts — the header files** `ds4.h` and `ds4_gpu.h`. These are not compiled into the program; a header file *declares* what functions exist so that separate `.c` files can agree on an interface. `ds4.h` is the engine's public API; `ds4_gpu.h` is the ~80-function API a GPU backend must provide. They are the two seams the next section is about. ### How the pieces fit — the layered architecture The files above are not a flat pile. They stack in **three layers**, joined by **two contracts**: ``` +------------------------------------------------------------------+ | FRONT-ENDS - five executables, one driver file each | | | | ds4 ds4-server ds4-agent ds4-bench ds4-eval | | ds4_cli.c ds4_server.c ds4_agent.c ds4_bench.c ds4_eval.c | +------------------------------------------------------------------+ | they use | ds4.h <--- the ENGINE API ONLY this | v +------------------------------------------------------------------+ | THE ENGINE - ds4.c | | | | load the GGUF model . tokenize text . run the 43-layer | | forward pass . own sessions + the live KV cache . CPU ref | +------------------------------------------------------------------+ | it uses | ds4_gpu.h <--- the GPU API ONLY this | v +---------------+----------------+ v v +--------------------------+ +--------------------------+ | ds4_metal.m | | ds4_cuda.cu | | + metal/*.metal kernels | | (CUDA kernels) | | macOS | | Linux / DGX Spark | +--------------------------+ +--------------------------+ a build links exactly ONE of these two ``` The two seams are the important idea: - **`ds4.h`** — the front-ends call the engine *only* through this. A front-end never touches a tensor or a model weight directly. `ds4_cli.c` is ~1,470 lines precisely because the engine does the hard work behind `ds4.h`. - **`ds4_gpu.h`** — the engine drives the GPU *only* through this. The engine never contains a line of Metal or CUDA. That is why one `ds4.c` serves both backends unchanged (you confirmed this earlier: ~one file differs between the Metal and CUDA builds). Read top to bottom, a prompt flows: a front-end renders text and tokens → hands them to the engine via `ds4.h` → the engine schedules 43 layers and issues kernel calls via `ds4_gpu.h` → the backend runs them on the GPU → logits flow back up. Every later module is a zoom-in on one box or one seam of this picture. ### From source to a running program DS4 is C (with one Objective-C file for Metal). Turning C source into a runnable program takes two steps — and understanding them makes every `.o` in the `Makefile` clear. **Step 1 — compile.** A *compiler* translates each source file (`.c` / `.m`), on its own, into an **object file** (`.o`). An object file holds the machine code for that one source file — but it is **not yet runnable**: wherever the code calls a function defined in a *different* source file, the object file just leaves a labelled hole. **Step 2 — link.** The *linker* takes a set of object files and connects them — every hole in one object file is matched to the function that defines it in another. The result is one runnable **executable**. ``` STEP 1 - COMPILE : each source file -> one object file ds4_cli.c --[ compiler ]--> ds4_cli.o \ ds4.c --[ compiler ]--> ds4.o | machine code, but ds4_metal.m --[ compiler ]--> ds4_metal.o | each still has holes linenoise.c --[ compiler ]--> linenoise.o / where it calls others STEP 2 - LINK : many object files -> one executable ds4_cli.o + ds4.o + ds4_metal.o + linenoise.o | [ linker ] fills every hole: each call is | wired to the definition it needs v ds4 <-- a runnable program ``` This two-step model is *why* the project is many `.c` files instead of one giant file: each compiles independently, and a rebuild only recompiles what changed. With that, the `Makefile` reads directly. The macOS variable `CORE_OBJS` ([Makefile line 18](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/Makefile#L18)) is `ds4.o ds4_metal.o` — the engine plus a backend. Every executable is `CORE_OBJS` plus its own driver object, plus any shared helpers: ``` CORE_OBJS = ds4.o (the engine, from ds4.c) + ds4_metal.o (the backend, from ds4_metal.m) <- macOS or ds4_cuda.o (the backend, from ds4_cuda.cu) <- Linux ds4 = CORE_OBJS + ds4_cli.o + linenoise.o ds4-server = CORE_OBJS + ds4_server.o + ds4_kvstore.o + rax.o ds4-agent = CORE_OBJS + ds4_agent.o + ds4_kvstore.o + linenoise.o ds4-bench = CORE_OBJS + ds4_bench.o ds4-eval = CORE_OBJS + ds4_eval.o ``` Because `ds4.o` (compiled from `ds4.c`) is inside `CORE_OBJS`, a change to `ds4.c` forces **all five** executables to recompile and relink. The build graph itself is telling you that `ds4.c` is the shared heart of the project. ### Three backends The same source compiles three ways, selected at build time: - `make` on macOS → the **Metal** backend (the primary, production target). - `make cuda-spark` / `make cuda-generic` on Linux → the **CUDA** backend. - `make cpu` → a **CPU** reference build (compiled with `-DDS4_NO_GPU`), for correctness checking and diagnostics only. The CPU path is debug-only. `AGENT.md` warns of "kernel VM failures with very large mappings," and the [`README`](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/README.md) is blunter: running the CPU code on current macOS *will crash the kernel* because of an OS virtual-memory bug. Never run the CPU build on a Mac — if you instrument the CPU path, do it on Linux. ## Zoom out — transformer You do not need transformer internals here, but you do need the **lifecycle** every one of the five front-ends drives, so the engine's responsibilities stop being abstract. Every inference looks like this: ``` "Write a haiku about RAM." | v TOKENIZE text -> a list of integer token IDs [ 1271, 84, 920, ... ] | v PREFILL run all 43 layers over the whole prompt +--------------------+ in one pass; fill the KV cache | 43 model layers | +--------------------+ | v the model now has a prediction for the next token | +===================== DECODE LOOP =========================+ | | | predicted next token --[ SAMPLE ]--> one chosen token | | ^ | | | | v | | +---- run 43 layers for that 1 token <--+ | | | +============ repeat until end-of-text or limit ============+ | v DETOKENIZE token IDs -> text "Silicon whispers ..." ``` Two phases, and the asymmetry between them shapes the whole engine. **Prefill** digests the prompt in bulk — one pass, many tokens. **Decode** generates new tokens one at a time, re-running all 43 layers for each single token. The *tokenize / detokenize* ends, the *prefill / decode* middle, and the KV-cache state that the loop depends on are each the subject of a dedicated module later. ## Zoom out — CS **Separate compilation and linking** is a foundational CS idea, and DS4 is a clean example of it. The deep point: a program is built from independent *translation units* (one per source file), each compiled in isolation to an object file, then a *linker* resolves the cross-references — the "holes" — into one executable. Why is it done this way instead of compiling one giant file? Two reasons, both visible in this repo: 1. **Incremental builds.** Change `ds4_cli.c` and only `ds4_cli.o` must be recompiled before relinking. On an 18,000-line engine, recompiling everything on every edit would be unbearable. The `Makefile` is a dependency graph precisely so it can rebuild the minimum. 2. **Modularity enforced by the toolchain.** Because `ds4.c` becomes one object file exposing only what `ds4.h` declares, a front-end physically *cannot* reach into the engine's internals — the linker only connects declared symbols. The layered architecture diagram above is not a convention you have to remember; it is mechanically enforced by how the program is built. That second point is the bridge to a larger idea you will meet again in Modules 3 and 5: a system stays comprehensible when its parts talk only through narrow, declared **interfaces** (`ds4.h`, `ds4_gpu.h`) rather than reaching into each other. To study this properly: read about *translation units* and *the linker* (any text on the C build model — e.g. the early chapters of "Computer Systems: A Programmer's Perspective" cover linking well). ## Exercise **Part A — paper, do it now (no build needed).** Using only the layered-architecture diagram and the file tour: 1. A bug makes the GPU produce slightly wrong attention numbers. Which file(s) could the bug be in — and which files can you *rule out*? 2. A bug makes the HTTP server mis-parse a JSON request. Which file? 3. You change the tokenizer. Which executables are affected? **Part B — [needs build], do it later.** Once you have a build: 4. Run `make` (macOS) or `make cpu`. Watch the order: every `.o` is compiled, then executables are linked. 5. Run `./ds4 --help` and `./ds4-server --help`; skim the flags. 6. Run `touch ds4.c` then `make` again. How many executables rebuild? Why?

What you should have found

1. The wrong attention numbers are in a **GPU backend**: `ds4_metal.m` + `metal/*.metal` (or `ds4_cuda.cu`). You can rule out all five front-ends (they never touch tensors) and *mostly* rule out `ds4.c` — though the engine *schedules* the kernels, the arithmetic itself lives in the backend. Module 5 is where you would actually hunt this. 2. JSON request parsing is in `ds4_server.c` — it is the only file that speaks HTTP. Not the engine, not the other front-ends. 3. The tokenizer lives in `ds4.c` (the engine), so **all five** executables are affected — they all link `ds4.o` via `CORE_OBJS`. 4. After `touch ds4.c`, **all five** executables rebuild: `ds4.c` → `ds4.o` is in `CORE_OBJS`, which every executable links. The build graph is telling you, mechanically, that `ds4.c` is the shared heart of the project.

## Deep check On Linux, plain `make` does not build anything — it prints help. Find the `Makefile` lines responsible and explain *why* the project chose this. (Hint: compare the macOS [`all:`](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/Makefile#L38) with the Linux [`all:`](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/Makefile#L72), and read the Linux `help` text and the `cuda-spark` / `cuda-generic` / `cuda` rules just below it.)

Answer

On Linux, `all: help` ([line 72](https://github.com/antirez/ds4/blob/1aedee468d782f4159a0b3d36816c4a3787bd580/Makefile#L72)) — there is no default build. A CUDA build needs an architecture decision the `Makefile` refuses to make for you: `cuda-spark` omits the `-arch` flag entirely (fastest on the GB10), `cuda-generic` uses `-arch=native`, and `make cuda CUDA_ARCH=sm_N` takes an explicit target. Guessing wrong silently produces a slow or non-running binary. So the build **refuses to guess** and makes you choose. macOS has exactly one GPU target (Metal), so there `all:` builds directly. The build graph encodes a real engineering judgment: *fail loudly on an ambiguous choice rather than pick a bad default.*

## Transferable takeaway A codebase is not its files — it is its *seams*. DS4's hundred-thousand-plus lines collapse into a simple shape once you see the two contracts: front-ends talk to the engine only through `ds4.h`; the engine talks to the GPU only through `ds4_gpu.h`. Three layers, two interfaces. When you meet any large unfamiliar codebase, **find its interface seams first** — they turn a pile of files into a system you can reason about. And read its build definition early: it shows you those seams, and the load-bearing files, for free. → Next: [Module 1 — The model & the cost of attention](07-the-model.md).

06 Orientation