Most tool documentation shows one box and one arrow. TDK CLI is bigger than that. A single tdk up passes through TypeScript commands, Starlark discovery and generators, a generated Tiltfile, Docker containers, a Traefik proxy, and a set of checks that run before anything starts.

This article draws the whole system in one Mermaid diagram, then walks through it. The diagram follows the repository's own maintainer guide (docs/TOPOLOGY.md) and the folders I read in the source. Some labels are summaries, so check the names against the repo before you rely on a single one.

The diagram 

flowchart TD %% ---------- People and clients ---------- DEV["Developer at a terminal"] AGENT["AI agent: Codex or Claude Code"] IDE["IDE and editor"] %% ---------- Inputs you own ---------- subgraph INPUTS["Inputs you own"] PROJ[".tdk/project.json"] SVC["service.json per service"] SRC["Application source code"] TILTF["Project Tiltfile"] ENVF["Environment files and secrets"] end %% ---------- CLI in TypeScript ---------- subgraph CLI["CLI in TypeScript: cli/src"] direction TB CMDS["commands: project, resource, up, down, status, logs, ui, doctor, config, mcp"] CFG["config and types"] GEN["generator: Handlebars project files"] FEPROV["frontend-frameworks: react, vue, svelte, solid, preact, lit, qwik, vanilla, tanstack-router"] BEPROV["backend-languages: bun, go, python, rust"] BFW["backend-frameworks: hono, express, elysia, fastify, nestjs, koa, h3, mcp"] MCPSRV["mcp server over stdio: doctor, up, down, status, logs, resource_list"] UI["ui: terminal dashboard"] UTIL["utils and components"] end %% ---------- CLI templates ---------- subgraph TPL["CLI templates: cli/templates"] TPLT["Tiltfile.hbs"] TPLS["spec.master.hbs"] TPLSTACK["TILT_TECH_STACK.star.hbs"] TPLDEF["TILT_RESOURCE_DEFAULTS.star.hbs"] end %% ---------- Discovery in Starlark ---------- subgraph DISC["Discovery in Starlark: discovery/"] DORCH["discovery_orchestrator.star"] DREG["registry.star"] DMAN["manifest scan and validation"] DSNAP["snapshots"] end %% ---------- Engine in Starlark ---------- subgraph ENG["Engine in Starlark: engine/topologies"] direction TB subgraph GENS["tilt/generators"] GIDX["index.star"] GVITE["Vite and TypeScript configs"] GNPM["npm and bunfig config"] GPRISMA["Prisma config"] GENV["environment files and API helpers"] GAGENTS["AGENTS.md notice"] end subgraph RES["tilt/resources"] RDECL["resource declaration"] RORCH["orchestrator and generators"] RDEP["startup order and dependsOn"] RTRIG["triggers and live update"] end subgraph MAN["tilt/manifest"] MLOAD["manifest loader"] MSCHEMA["schema and constants"] end subgraph PLAT["platform"] PDOCK["docker: language and frontend Dockerfiles"] PNET["networking and Traefik"] PINFRA["Postgres and optional infra"] end end %% ---------- Generated runtime files ---------- subgraph GENOUT["Generated per service: .autogenerated"] DFILE["Dockerfile.app.autogenerated"] NGINX["nginx.autogenerated.conf"] VCONF["vite and tsconfig files"] APIC["api-client.ts and env.ts"] SNAP[".tdk-contract snapshots"] SYAML["service.yaml projection"] end %% ---------- Checks ---------- subgraph CHECKS["Checks"] DOCTOR["tdk doctor: host and canUp"] DRIFT["drift check: generated files vs snapshots"] DRYRUN["tdk up --dry-run: plan only"] MIGWARN["doctor warning: migration in start script"] READY["readiness: status and up JSON"] end %% ---------- Runtime ---------- subgraph RUNTIME["Runtime on your machine"] TILT["Tilt: builds, watches, live-updates"] DOCKER["Docker engine"] TRAEFIK["Traefik proxy"] PG["PostgreSQL"] SVCS["Service containers: frontends, APIs, workers, MCP servers"] NATS["NATS messaging when enabled"] end %% ---------- Outside the local loop ---------- subgraph PROD["Outside TDK: production"] HELM["Helm"] ARGO["Argo CD"] KUST["Kustomize"] end %% ---------- Flows ---------- DEV --> CMDS IDE --> SRC AGENT --> MCPSRV MCPSRV --> CMDS CMDS --> GEN GEN --> TPL CMDS --> FEPROV CMDS --> BEPROV CMDS --> BFW CMDS --> UI CMDS --> CFG CFG --> UTIL PROJ --> DORCH SVC --> DORCH DORCH --> DREG DORCH --> DMAN DMAN --> MLOAD DREG --> DSNAP TILTF --> DORCH TILTF --> RDECL RDECL --> RORCH RORCH --> GIDX GIDX --> GVITE GIDX --> GNPM GIDX --> GPRISMA GIDX --> GENV GIDX --> GAGENTS RORCH --> RDEP RDEP --> RTRIG MLOAD --> MSCHEMA RORCH --> PDOCK RORCH --> PNET RORCH --> PINFRA GENS --> GENOUT PDOCK --> DFILE PNET --> NGINX GVITE --> VCONF GENV --> APIC GENOUT --> SNAP GENOUT --> SYAML CMDS --> DOCTOR SNAP --> DRIFT DRIFT --> TILT CMDS --> DRYRUN RORCH --> MIGWARN TILT --> READY SRC --> TILT ENVF --> TILT TILT --> DOCKER DOCKER --> TRAEFIK DOCKER --> PG DOCKER --> SVCS DOCKER --> NATS TRAEFIK --> SVCS SVCS --> PG SVCS --> NATS HELM --> ARGO KUST --> ARGO %% ---------- Styling ---------- classDef cli fill:#e8f1ff,stroke:#1d4ed8,color:#0f172a classDef engine fill:#fff4e5,stroke:#c2410c,color:#0f172a classDef runtime fill:#e8fbef,stroke:#15803d,color:#0f172a classDef check fill:#fdecec,stroke:#b91c1c,color:#0f172a classDef prod fill:#f3f4f6,stroke:#6b7280,color:#0f172a class CMDS,CFG,GEN,FEPROV,BEPROV,BFW,MCPSRV,UI,UTIL cli class DORCH,DREG,DMAN,DSNAP,GIDX,RDECL,RORCH,RDEP,RTRIG,MLOAD,MSCHEMA,PDOCK,PNET,PINFRA engine class TILT,DOCKER,TRAEFIK,PG,SVCS,NATS runtime class DOCTOR,DRIFT,DRYRUN,MIGWARN,READY check class HELM,ARGO,KUST prod

How to read it

Start at the top left. A developer, or an agent over MCP, enters the CLI. The CLI has three jobs: scaffolding files through templates and providers, reading the project's commands, and starting the stack.

The middle of the diagram is the two-stage generation the maintainer guide describes. The CLI writes starter files in TypeScript. At Tilt time, Starlark discovery reads each service.json, and the engine's generators write the runtime files under .autogenerated/. Those files are what Docker and Tilt run.

The right side shows the checks. doctor answers whether the machine can run the stack. The drift check compares generated files with their snapshots before startup. The dry run prints the plan. The readiness output tells you, or an agent, when a service is ready.

The bottom shows the runtime: Tilt drives Docker, Docker runs the Traefik proxy, Postgres, the service containers, and NATS when it is enabled. Production sits outside the loop. The diagram ends with Helm, Argo CD, and Kustomize, because TDK does not generate cluster manifests by default.

Things the diagram leaves out

It does not show every module or every generator. The .tdk-contract snapshots, the optional observability stacks, and the golden image layer are simplified or omitted. Use the repo's topology guide when you need the full list.

Summary

TDK CLI is a loop: TypeScript commands write project files, Starlark generators turn service.json into runtime files, checks confirm the result, and Docker and Tilt run it. Keep the inputs in your hands, treat the generated files as output, and let the checks tell you when something has drifted.