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 prodHow 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.
Top comments (0)