The Largest Architecture Diagram You Have Never Seen: TDK CLI, End to End

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.