aiexplainer

"How LLMs work, from first principles": an interactive 3D explainer that starts from word-pair counts and adds one part per chapter until it reaches a production LLM. Every part is a machine drawn on the GPU and backed by a real tiny model trained for that chapter. Bun + Turborepo monorepo; why it is built this way, and the decisions behind it, live in specs/done/llm-explainer.

Active work

The live site is https://aiexplainer-red.vercel.app, deployed from main. Work happens on llm-explainer (each push builds a Vercel preview), and production is git push origin llm-explainer:main.

The next feature is specs/lab-hub: it retells the explainer for people with no tech background, as a build-up story set in one lab hall you fly through. Start at its Next Agent Prompt.

Layout

The tree splits by what each part owns. A concept has exactly one home. A second copy is a bug, so find the owner before writing a helper.

• apps/explainer: the site. It holds chapters as data, scene builders that turn model output into frames, the HUD, the lab review pages and the browser harness.
• packages/renderer: the WebGPU renderer (TypeGPU). It draws the FrameInput it is handed and never reads app state. It owns the camera math, label placement and the kit of scene primitives.
• packages/llm: the model runtime in plain TypeScript. It owns the manifest format, the tokenizer, the forward pass, sampling and the production-scale arithmetic.
• training: the PyTorch side, a uv project rather than a bun workspace. It trains, probes and exports every model into apps/explainer/public/models.
• assets/blender: Blender scripts that build the committed props (bun run props:build). Every asset can be reproduced from code.
• packages/typescript-config: the shared tsconfig base.
• .agents/skills: agent skills from dzhng/skills. .claude/skills symlinks into it. Read renderer before GPU work.

Conventions

• Workspaces ship TypeScript source directly ("exports": { ".": "./src/index.ts" }). Only the app has a build step.
• Each workspace defines whichever of build, check-types, lint and test it needs. The root runs them across the graph with turbo.
• Shared dependency versions live in the root catalog and are referenced as "catalog:". typegpu and math are young, so they are pinned exactly.
• Greenfield: hard cutovers, no compatibility shims.

Commands

bun install
cd training && uv sync && cd ..   # the Python env, only needed to retrain
bun run verify                    # format, types, lint, bun tests, training tests
bun run format

The browser harness, which runs on a real GPU, is described in apps/explainer.

Ratchet Files

Source files are limited to 8,000 estimated tokens (bytes divided by four). The pre-commit hook runs scripts/check-file-size.mjs through lint-staged. bun install runs scripts/install-git-hooks.mjs, which installs the hook once in the repository's shared hooks directory, so every linked worktree runs it; each checkout that commits needs its own bun install, and commits from one without dependencies are refused. Installing a branch from before this change re-enables Husky for every checkout until a current branch runs bun install again. Existing oversized authored files are frozen at their current size; generated and vendored paths are excluded through .gitattributes. A file may use @ratchet-files-ignore in its first 10 lines only when splitting it would cost more than it saves, with the reason beside the pragma.