DEV Community: tdk-cli

tdk

tdk-cli — Sun, 18 Oct 2026 20:48:48 +0000

Must Read for Vibe Coders: The Five Habits That Separate a Demo From a Product

tdk-cli — Sun, 18 Oct 2026 19:56:41 +0000

If you vibe-code, read this before you share anything you built. An agent can produce a working app in an afternoon. What it cannot do is check that the app works on a second machine, with a second person, or after a restart. That gap is where most vibe-coded projects break, and it is what these five habits close.

1. Run it from a clean copy

Your machine has things the repository does not: a global tool, an old environment variable, a file you never committed. Clone the project into an empty folder, follow the README, and run it. If it fails, the problem is real, and you found it before a user did.

2. Keep secrets out of the code and the chat

Agents often copy an example key into real code, and a key pasted into a prompt goes to a third party. Put every secret in an environment file that git ignores, read it at runtime, and rotate anything that has been exposed. A deleted commit does not undo a copy.

3. Read what changed before you accept it

You did not write most of the code, so you need a way to check it. Read the list of changed files first, then the summary, then the diff for anything that touches data, money, login, or secrets. Ask the agent what each change does in plain words, and treat a vague answer as a reason to look closer.

4. Test the failure, not only the success

A demo shows the happy path. Try an empty form, text where a number belongs, and a request while a dependency is down. The app should answer with a clear message, not a crash or a blank page. Write one test for each failure you can think of, and make sure the test fails when the behaviour breaks.

5. Keep the local setup in one place

If your app has more than one service, such as a frontend, an API, and a database, the start order and the ports matter. Describe the services in one place, start them with one command, and check their readiness before you test a flow. TDK CLI is one way to do this for local multi-service apps: tdk doctor --json checks whether the machine can run the stack, tdk up main --dry-run shows the plan, and tdk status --json reports readiness. It is for local development, and production stays with your existing deployment tools.

Before you share it

Run through the five habits once. Then ask one person to use the app without your help, and watch where they get stuck. That moment is the most useful test you will get.

Keep this page

Bookmark it, and read it again before each launch. The habits are short, and they are the ones that save the most time later.

Drift Checks in TDK CLI: Fail Fast, Generator Changes, and Catching Hand Edits Before Commit

tdk-cli — Sun, 18 Oct 2026 19:23:10 +0000

A drift check answers one question: has someone changed a generated file by hand? TDK runs that check before Tilt starts, so a hand edit stops the start before anything is built. A reader asked two follow-up questions, and this article answers them from the source: what happens when the generator itself changes, and whether the check should also run before commit.

How the check decides

The check compares each generated file under .autogenerated/ with its snapshot in .autogenerated/.tdk-contract/. The snapshot is the copy TDK wrote the last time it generated that file. The comparison is a byte-for-byte match on the file contents.

Only one kind of difference counts as drift. If a generated file differs from its snapshot, it was edited by hand, and tdk up stops and lists it. The fix the message offers is tdk config regenerate to discard the edits, or tdk up --ignore-drift to skip the check.

A different kind of difference is not drift. If service.json changed since the outputs were written, the outputs are stale, and tdk up regenerates them. That is the normal edit-then-start loop.

The service.yaml file is exempt. It is a runtime projection with timestamps, so it has no snapshot to compare.

Does a generator change look like drift?

The question is whether a legitimate change to a template or generator is flagged. From the code, the answer is no, and the reason is worth understanding.

The check has no notion of a generator version. It never asks which generator produced a file. It only asks whether the file on disk matches the snapshot written at the last generation. If the generator changed, the new output and the new snapshot are written together, so they still match. The check passes.

I did not run this against a real generator change, so treat it as a reading of the code rather than a tested result. It has one consequence worth knowing. A file that an older generator wrote still matches its snapshot, so the check passes even though the current generator would produce something different. Staleness is invisible to this check. Only a hand edit, which differs from the snapshot, is flagged.

What this means in practice: upgrading TDK does not raise a false alarm. Equally, the check does not warn you that a generator upgrade changed your output. Review the diff after an upgrade, the same way you would review any dependency change.

Fail fast, and why it matters

Running the check before Tilt starts is the design choice a reader praised, and it is worth stating why. A check after the build finds the problem minutes later, after images have been built with the edited file. Checking first costs nothing and points at the file.

Should it run before commit?

The reader suggested a pre-commit check, so that a hand-edited generated file never reaches git. That is a sound idea, and TDK already has the pieces.

tdk config verify checks the wider generated project and compares the generated service files with their snapshots. tdk doctor covers local readiness and discovered service problems. The repo's contributor guidance keeps those two distinct, so a pre-commit hook should call tdk config verify, not tdk doctor, when it is checking generated files.

Two things to settle first:

Whether generated files are committed. If .autogenerated/ is ignored by git, a hand edit never reaches the repository, and the pre-commit check guards only your local copy. Check your .gitignore before you decide.
Whether snapshots are committed. The snapshots must travel with the project for a teammate's check to mean anything.

A sketch of the pre-commit step

tdk config verify

Run it from the project root in a git pre-commit hook, and make it fail the commit when it exits non-zero. Keep the hook fast, since it runs on every commit.

Summary

The drift check compares each generated file with the snapshot from its last generation. It blocks a start on a hand edit, not on a stale output. It does not flag a legitimate generator change, and it cannot see that an output is stale after a generator upgrade, so review generator upgrades yourself. Before commit, tdk config verify is the right command to call, and the first question to answer is whether your generated files are committed at all.

What Really Happens to Your Data When You Type tdk up: A Sequence Diagram With the Database

tdk-cli — Sun, 18 Oct 2026 19:21:20 +0000

The earlier diagrams followed the containers. Most real problems in a local stack are about data: a table that is missing, a seed that ran twice, a database that came back empty. This article extends the tdk up sequence to cover the database, so you can see where the data lives and what each step does to it.

The facts below come from TDK's data guide, which records what was run against a real Postgres container, and from the open issues. Where something is not verified, the article says so, and the diagram marks those steps.

The sequence

sequenceDiagram
    autonumber
    actor Dev as Developer
    participant CLI as tdk CLI
    participant Tilt as Tilt
    participant PG as Postgres container (one per project)
    participant Vol as Named volume
    participant Mig as migrator resource
    participant Seed as seed job (optional)
    participant API as API service (per stack)

    Dev->>CLI: tdk up
    CLI->>Tilt: start the project
    Tilt->>PG: start project_postgres on host port 15432 or TDK_POSTGRES_PORT
    PG->>Vol: mount database-management_project_postgres_data
    Vol-->>PG: existing data reused, or empty on first run
    PG-->>Tilt: ready to accept connections

    Note over Tilt,PG: DATABASE_URL points each service at project_stack

    Tilt->>Mig: run migrations once, in their own resource
    Mig->>PG: apply pending migrations in order
    PG-->>Mig: applied migrations recorded
    Mig-->>Tilt: done

    opt seed job is declared
        Tilt->>Seed: run seed as one-shot job, restart no
        Seed->>PG: insert fake data
        Note over Seed,PG: order against migrator and API not verified yet
    end

    Tilt->>API: start after dependencies
    API->>PG: connect with DATABASE_URL
    PG-->>API: queries served
    API-->>Tilt: health route answers

    Dev->>CLI: tdk down
    CLI->>Tilt: tear down
    Tilt->>PG: remove the container
    Note over PG,Vol: the named volume is kept, so the data survives

What lives where

TDK runs one Postgres container for the whole project. The container is named after the project, such as my_shop_postgres. Each stack gets its own database inside it, named from the project and the stack. Services in the same stack share that database, through the DATABASE_URL in their generated configuration.

The data sits in a named volume. The data guide checked that tdk down removes the container but keeps the volume, so the next tdk up starts Postgres on the same data. That is the most useful fact in this article, and also the most surprising one, because a fresh container does not mean a fresh database.

The host port defaults to 15432, or whatever TDK_POSTGRES_PORT says. The data guide gives 15432 as the host port, and an earlier scratch run chose it when 5432 was taken.

The migrator

Migrations run in their own resource, the migrator, which the repo's contributor guidance requires for new examples. It starts after Postgres is ready and before the API. Migrations are applied once, in order, and the migration tool records which ones have run, so a restart does not reapply them. The exact recording depends on the migration tool you choose.

If the database comes back empty after a reset, the migrator runs again on the next tdk up, or when you restart the migrator resource in Tilt. An empty database is not an error. It is the state before the migrations run.

Seeding

A seed loads fake data for development. The data guide suggests two options. A SQL file applied by hand is fine for a pilot. A one-shot resource is the other option: the seed runs as a bring-your-own job with --restart no, the same way as a migration.

The guide also says the order of the seed, the migrator, and the API is not verified. The safe answer is to make the seed idempotent, so running it in a different order does no harm. The open issue that would make startup order explicit for Postgres is #531.

Keep seed data fake. Never put production data in the repository.

Resetting the data

Two resets are covered by the guide. To reset everything, stop the stack, remove the volume, and start again. To reset one stack, drop and recreate its database while Postgres is running, using DROP DATABASE ... WITH (FORCE) so the service disconnects first.

Each reset has a cost. Removing the volume deletes every stack's data. Dropping one database deletes only that stack's data, but the services in that stack lose their state until the migrator runs again.

Snapshot and restore

The guide also describes a snapshot and restore for one database. Take the snapshot before a risky change, and test the restore once. A backup you have never restored is a guess.

What the diagram does not show

It does not show the exact order of the seed, the migrator, and the API, because that order is not verified in the guide. It does not show how a migration tool such as Prisma, Drizzle, Atlas, or Dbmate runs its own steps, since that depends on your choice. And it assumes one Postgres per project, which is how the data guide describes TDK.

Summary

One tdk up starts one Postgres for the project, mounts a volume that outlives the container, runs the migrator once, optionally runs a seed, and then starts the API against its stack's database. tdk down removes the container and keeps the data. Read the volume, not the container, when you ask where your data went.

What Really Happens When You Type tdk resource: A Sequence Diagram of Scaffolding

tdk-cli — Sun, 18 Oct 2026 19:19:16 +0000

The earlier sequence diagram followed tdk up. This one follows the command you run before any of that: tdk resource, which creates a new service. It is the step where a project gets its first source files, so it is worth knowing what happens in order.

The steps below follow what I saw when I ran the command in a scratch project, and the provider and template structure in the repo. The messages are summaries of real output, so check exact wording against your version.

The sequence

sequenceDiagram
    autonumber
    actor Dev as Developer
    participant CLI as tdk CLI (TypeScript)
    participant Root as Project root finder
    participant Prov as Framework or language provider
    participant Tpl as Templates and generator
    participant FS as Project folder on disk
    participant Disc as Discovery paths in .tdk/project.json

    Dev->>CLI: tdk resource storefront-web --type frontend -y
    CLI->>Root: find .tdk/project.json from here upward
    alt no project found
        Root-->>CLI: not found
        CLI-->>Dev: error, run tdk project --yes first
    else project found
        Root-->>CLI: project root and config
        CLI->>CLI: validate name, type, framework, and stack
        CLI->>Prov: ask for starter files for the chosen framework
        Prov-->>CLI: package.json, entry file, component, test, tsconfig
        CLI->>Tpl: fill the Dockerfile and service.json
        Tpl-->>CLI: rendered files
        CLI->>Disc: check the target path against discovery paths
        alt path outside discovery
            Disc-->>CLI: services/*/* is the default, apps/ is not scanned
            CLI->>FS: place the resource under services/<stack>/<name>
            CLI-->>Dev: placed here instead of apps/, use --path to choose
        else path inside discovery
            CLI->>FS: write files under the chosen folder
        end
        FS-->>CLI: files written
        CLI-->>Dev: resource created, next steps: bun install, tdk up <stack>
    end

    Note over Dev,FS: Generated runtime files under .autogenerated are not written here
    Dev->>CLI: tdk up main --dry-run
    CLI-->>Dev: plan shows the new service, no containers started

The steps that matter

The project root. The command searches upward for .tdk/project.json. Run it outside a project and it stops with a clear message, and the fix is tdk project --yes first. Creating a project and adding a resource are separate steps.

The checks. The CLI validates the name, the resource type, the framework, and the stack before it writes anything. A bad combination is rejected here, not after files have been created.

The provider. The framework or language provider owns the starter files: a package.json, an entry file, a component, and a test for a frontend. TypeScript providers write these, not templates. This is why the frontend scaffold and the Rust scaffold look different.

The placement check. This is the step that surprised me most. The command compares the target folder with the discovery paths in .tdk/project.json. In the default setup those paths are services/*/*, so a resource requested under apps/ would never be started by tdk up. The CLI places it under services/<stack>/<name> and tells you why. The --path option overrides the choice.

The files on disk. The resource folder receives its source files and a service.json. The runtime files are not written here. They appear later, when Tilt loads the project and the engine generates the .autogenerated folder.

Where to look next

After the command, tdk up main --dry-run shows the new service in the plan without starting containers. The first sequence diagram covers what happens at that point.

Common surprises

The resource is not where you asked. Check the message for the placement reason, and use --path if you need another location.
tdk up does not see the new service. Check that the folder is inside a discovery path.
The frontend needs its dependencies installed. The next-steps output says so. Run the install before the first start.

Summary

tdk resource is a short chain: find the project, check the inputs, ask a provider for starter files, render the manifest, check the placement, and write the folder. Most surprises come from the placement step, so read its message before you assume the files went where you wanted.

Bookmark It: Stop Shipping Broken Vibe Code (Round Two): 10 More Checks Before Launch

tdk-cli — Sun, 18 Oct 2026 18:23:31 +0000

Your demo works. Good. Now give the app to someone who did not build it.

That is where most vibe-coded projects fall apart. Not because the agent was careless, but because the demo never tested the things that only show up on a second machine, with a second person, or after a restart. Bookmark these ten checks and run them before you call the app ready.

1. The lockfile matches the manifest

Run the exact install command your CI runs, on a clean copy. Agents edit the manifest and forget to regenerate the lockfile. The result is a build that passes on your laptop and fails in the pipeline.

2. Every outbound call has a timeout

A call with no limit waits forever when the other side stalls. Give each one a deadline, and check what the user sees when it expires.

3. Errors are readable

Send an empty form, text where a number belongs, and an oversized value. The app should answer with a message a person can act on, not a stack trace or a blank screen.

4. Nothing secret is in the repo

Search the diff for keys and connection strings. Move every value to the environment. Confirm the environment file is git-ignored with git status.

5. The database starts before the code that needs it

An API that boots before its database accepts connections fails its first request in a confusing way. Declare the order. In TDK CLI, dependsOn in service.json sets it, and tdk up main --dry-run prints the start order without starting anything.

6. Migrations run once, in their own step

A migration in your app's startup runs on every restart, and two instances can run it at once. Move it to a separate step that runs before the app. TDK CLI runs migrations in a migrator resource, and tdk doctor warns when a service runs one from its start script.

7. Generated files are never hand-edited

A Dockerfile or routing file you change by hand is overwritten by the next generation, quietly. Change the source and regenerate. TDK CLI compares its generated files with saved snapshots before tdk up starts, so a hand edit stops the start and names the file.

8. The health check tells the truth

A route that returns 200 every time says the process is alive, not that the service works. Check what the service actually needs, and keep the check cheap enough to run often.

9. A teammate can start it from a clean clone

Clone into an empty folder, follow your README, and run one command. If it fails, your app depends on something that only lives on your laptop. Find it, and write it down.

10. You can read the failure

Stop the database on purpose. Throw an error in one route. Remove one environment variable. The log should say what broke and where. If it doesn't, fix that before anyone else sees the app.

The short version

Run all ten once. Most vibe-coded projects pass the first few and fail on the last few. The fixes are small, and each one saves a conversation you would rather not have.

For a multi-service app, the local stack is where most of the second-machine problems show up. With TDK CLI, start with tdk doctor --json to confirm the machine can run it, then tdk up, then tdk status --json until everything reports ready. If something fails, tdk logs --json --service <name> --tail 200 shows the first error.

Your demo is not the product. The demo that survives a clean clone and a teammate's laptop is.

For Empowering the TDK Community

tdk-cli — Sun, 18 Oct 2026 18:09:31 +0000

I want to share where TDK CLI stands and invite you to take part in it. This is not a launch and it is not a finished product. It is a working tool with real users, real gaps, and a public list of work that needs hands.

What TDK CLI is

TDK CLI is a command-line tool that runs a multi-service application on your machine. You describe each service in a service.json file, and TDK generates the Docker and Tilt files from those descriptions and starts the stack with tdk up. It is for local development. Production deployment stays with tools such as Helm, Argo CD, or Kustomize.

The core CLI is MIT-licensed and needs no key to run.

Where it is honest about its state

The README describes TDK as 1.x for local development. That means the core commands and the service.json model are in use, and the project still changes. Some areas are marked as opt-in, such as the Go and Rust language providers, and some premium features need a license key. Check the docs for the feature you plan to use before you depend on it.

The project publishes its open issues, and a good number are labelled for newcomers. Treat the tracker as the honest record of what is unfinished.

What it does day to day

Scaffold services. tdk resource <name> --type <type> creates frontends, backends, workers, MCP servers, and other resource types.
Start the stack. tdk up builds and runs the services, and tdk up <stack> starts one part of a larger system.
Check before it starts. tdk doctor --json reports whether the machine can run the stack. tdk up main --dry-run shows the plan.
Watch it run. tdk status --json reports readiness, tdk logs --json gives recent output, and tdk ui opens a terminal dashboard.
Work with agents. tdk mcp runs a local Model Context Protocol server, so an assistant can start the stack and read its status.

Ways to take part

If you use TDK, tell us what you built. A short note in the community discussions helps the next person decide whether the tool fits their work.

If you write about it, link to the repository and the docs, and say what you tried. Accurate posts are the most useful ones.

If you want to contribute code, start with the labels. Documentation and translation issues are the usual first step, and tests come next. The contributing guide explains the sign-off rule: every commit needs a Signed-off-by line, added with git commit -s.

If you maintain a project that uses TDK, add it to the list of adopters, so the next team can see who else runs it.

Ways to help without writing code

Report a bug with the exact command, the output, and your version. Improve a translation. Try the example repositories, such as the ERP example, and tell us which part confused you. Read the docs and note where they are unclear.

What we are still working on

Some of the work is visible in the issue tracker: better error messages, more tests, and clearer documentation for newcomers. Some of it is harder, such as keeping generated files consistent across many services. We would rather say that plainly than promise a date.

Join us

Pick one thing from this list and do it this week. Open an issue, fix a typo, or try a stack you have never run. The community is only as useful as the people who show up with something specific to say.

Thanks to everyone who has already opened an issue, sent a pull request, or written about TDK.

The Bank App Architecture Diagram: How a Retail Banking Stack Could Run Locally With TDK CLI

tdk-cli — Sun, 18 Oct 2026 18:03:55 +0000

Banking apps are a good test of an architecture diagram, because every box has a rule attached. Accounts must never go negative without a rule allowing it, a transfer must happen once and only once, and customers must see only their own data. This article draws one reference layout for a retail banking app and shows how TDK CLI could run its services locally.

This is an illustrative design. It is not taken from a real bank, and the repository on my machine has no bank application. The only banking service in the ERP example is banking-integration-api, which is a finance-side bank connection, not a customer-facing app.

Do not use this for real money without a security review and the compliance work your jurisdiction requires. A local stack with fake accounts is a teaching tool, not a bank.

The diagram

flowchart TD
    CUST["Customer on a phone or browser"]
    OPS["Bank operator console"]

    subgraph EDGE["Edge: frontends and gateway"]
        WEB["web-banking-app: frontend"]
        OPSAPP["ops-console-app: frontend"]
        GW["Traefik gateway with TLS in production"]
    end

    subgraph IDENT["Identity and access"]
        AUTH["auth-api: login, sessions, MFA hooks"]
        CUSTDATA["customer-profile-api"]
    end

    subgraph CORE["Core banking services"]
        ACCTS["accounts-api: balances and account types"]
        LEDGER["ledger-api: double-entry postings"]
        TRANS["transfers-api: idempotent transfers"]
        CARDS["cards-api: card status and limits"]
    end

    subgraph RISK["Risk and rules"]
        FRAUD["fraud-rules-api: scoring and holds"]
        LIMITS["limits-api: daily and per-transfer limits"]
    end

    subgraph INTEG["Integrations"]
        PAYS["payments-gateway-api: external rails"]
        NOTIFY["notifications-api: email and SMS"]
    end

    subgraph JOBS["Background work"]
        STMT["statements-worker: monthly statements"]
        RECON["reconciliation-worker: match external settlements"]
    end

    subgraph DATA["Data and messaging"]
        PG[("PostgreSQL: one database per domain")]
        NATS["NATS: transfer and posting events"]
    end

    subgraph AUDIT["Audit and observability"]
        AUDLOG["audit-log-api: append-only record"]
        TRACE["traces and logs with correlation IDs"]
    end

    CUST --> WEB
    OPS --> OPSAPP
    WEB --> GW
    OPSAPP --> GW

    GW --> AUTH
    GW --> CUSTDATA
    GW --> ACCTS
    GW --> TRANS
    GW --> CARDS

    AUTH --> CUSTDATA
    TRANS --> FRAUD
    TRANS --> LIMITS
    TRANS --> LEDGER
    TRANS --> PAYS
    LEDGER --> ACCTS
    CARDS --> LIMITS

    TRANS --> NATS
    LEDGER --> NATS
    NATS --> NOTIFY
    NATS --> AUDLOG
    NATS --> RECON
    STMT --> LEDGER

    ACCTS --> PG
    LEDGER --> PG
    TRANS --> PG
    CUSTDATA --> PG
    AUDLOG --> PG

    CORE --> AUDLOG
    CORE -.-> TRACE
    AUTH -.-> TRACE

    classDef money fill:#e8fbef,stroke:#15803d,color:#0f172a
    classDef risk fill:#fdecec,stroke:#b91c1c,color:#0f172a
    classDef audit fill:#fff4e5,stroke:#c2410c,color:#0f172a
    class LEDGER,TRANS,ACCTS,CARDS money
    class FRAUD,LIMITS risk
    class AUDLOG,TRACE audit

How to read it

Customers and operators reach the system through two frontends. Both pass through one gateway, which in production would terminate TLS and handle authentication before a request reaches a service.

The core services are the money path. The ledger records every movement as a double-entry posting, so each transfer debits one account and credits another, and the books always balance. Transfers go through the fraud and limit checks before they post. Idempotency matters here: a retried transfer must not move money twice, so the transfers service keys each request.

Events on NATS carry transfers and postings to the services that react to them: notifications, the audit log, and reconciliation. Statement generation reads from the ledger on a schedule, as a background worker.

The audit log is append-only. Nothing in the diagram writes to it except the event flow, and nothing edits or deletes its rows. Traces and logs carry a correlation ID, so a single transfer can be followed across services.

Mapping it to TDK CLI

In a TDK project, each box in the diagram becomes a resource. The frontends are frontend resources, the APIs are backend resources, and the statements and reconciliation jobs are worker resources. Each gets a service.json, and dependsOn declares the order: the database first, then the ledger, then the transfers service that posts to it.

TDK runs the local stack and checks it before startup. The drift check stops a hand edit to generated files, the dry run prints the start order, and readiness output shows which services are up. Those checks help a team keep the local system consistent. They do not make the design safe.

tdk up main --dry-run
tdk status --json

What the diagram does not cover

It leaves out the controls a real bank needs: customer identity verification, regulatory reporting, key management, backup and disaster recovery, penetration testing, and the rules for storing account data. Each of those needs a specialist, and none is solved by a diagram.

It also says nothing about performance. A transfer service under load is a different problem from a transfer service on a laptop.

Summary

A retail banking app is a set of services around a double-entry ledger, with transfers, limits, fraud checks, an append-only audit log, and events that connect them. Drawn as one diagram, it shows where the money moves and where the checks sit. Use it to teach the layout and to build a local sandbox with fake accounts. Anything closer to production needs a security review and the compliance work that applies where you operate.

The ERP Architecture Diagram: Seven Domains, One Local Stack

tdk-cli — Sun, 18 Oct 2026 17:43:09 +0000

An enterprise resource planning system is hard to draw because it is wide. The tdk-erp-system example has seven business domains, each with its own backend services and a frontend, plus shared platform pieces. This article draws the whole layout in one Mermaid diagram.

The dashboard-to-API edges in the diagram come from dependsOn entries in the repo's service.json files. In the manifests I read, each of those dependencies sits inside one stack. The arrows from the developer and from the stacks to the platform are my simplification, not declared dependencies.

The diagram

flowchart LR
    DEV["Developer runs tdk up with a stack name"]

    subgraph PLAT["platform: shared infrastructure"]
        PDB["database-management: Postgres compose file"]
    end

    subgraph FIN["finance stack: 15 services in the README"]
        FAPI["backend APIs on ports 4010 to 4024"]
        FGL["general-ledger-api"]
        FAR["financial-analytics-api"]
        FDASH["finance-dashboard-app on port 3010"]
    end

    subgraph HR["hr stack: 12 services in the README"]
        HAPI["backend APIs on ports 4100 to 4111"]
        HEP["employee-portal-api"]
        HPORT["hr-portal-app on port 3020"]
    end

    subgraph INV["inventory stack: 18 services in the README"]
        IAPI["backend APIs on ports 4200 and up"]
        IMG["inventory-management-api"]
        IAPP["inventory-management-app"]
    end

    subgraph SALES["sales stack: 20 services in the README"]
        SAPI["backend APIs on ports 4300 and up"]
        SCRM["crm-api"]
        SAPP["sales-crm-app"]
    end

    subgraph MFG["manufacturing stack: 15 services in the README"]
        MAPI["backend APIs"]
        MPP["production-planning-api"]
        MAPP["production-control-app"]
    end

    subgraph SC["supply_chain stack: 12 services in the README"]
        SAPIC["backend APIs"]
        SCP["supply-chain-planning-api"]
        SCAPP["supply-chain-app"]
    end

    subgraph ANA["analytics stack: 8 services in the README"]
        AAPI["backend APIs on ports 4600 to 4607"]
        ABI["business-intelligence-api"]
        ABIAPP["bi-dashboard-app on port 3070"]
    end

    DEV --> FIN
    DEV --> HR
    DEV --> INV
    DEV --> SALES
    DEV --> MFG
    DEV --> SC
    DEV --> ANA

    FIN --> PLAT
    HR --> PLAT
    INV --> PLAT
    SALES --> PLAT
    MFG --> PLAT
    SC --> PLAT
    ANA --> PLAT

    FDASH -->|"dependsOn"| FAR
    HPORT -->|"dependsOn"| HEP
    IAPP -->|"dependsOn"| IMG
    SAPP -->|"dependsOn"| SCRM
    MAPP -->|"dependsOn"| MPP
    SCAPP -->|"dependsOn"| SCP
    ABIAPP -->|"dependsOn"| ABI

How to read it

The developer enters through one command, and each stack can be started on its own, such as tdk up finance. The platform folder holds a Postgres compose file (database-management). I have not checked how each stack connects to it, so the arrows from the stacks to the platform show a shared-infrastructure idea rather than a verified wiring.

Each dashboard depends on the API it calls, and the edge shows that dependency. The start order follows from it: the API starts first, then the dashboard. The dependsOn lists in the repo are the source of truth, so the diagram should be updated when they change.

The port blocks are visible in the names. Finance backends use 4010 to 4024, and HR starts at 4100. Analytics uses 4600 and up. Frontends sit in the 3000 range, with finance on 3010, HR on 3020, and analytics on 3070. Inventory, sales, manufacturing, and supply chain show their ranges more loosely, because I did not list every port for them in this article.

What the numbers say

The README gives 15, 12, 18, 20, 15, 12, and 8 services for finance, HR, inventory, sales, manufacturing, supply chain, and analytics. The manifest counts I took directly from the folders differ by one for several stacks, because a frontend and its backend may be counted differently. Check the folder before you rely on a single number.

What the diagram leaves out

It does not draw every service, every port, or every generated file. It shows the domain layout and the dependencies that the manifests declare. For a single stack, the stack walkthrough articles in the series show the services in detail.

Summary

The ERP example is seven domain stacks on one shared platform. Each stack has backends, a dashboard or portal, and dependencies declared in its own manifests. Start one stack at a time, and let the dependsOn edges decide the order inside it.

What Really Happens When You Type tdk up: A Sequence Diagram of TDK CLI

tdk-cli — Sun, 18 Oct 2026 17:41:50 +0000

The first architecture diagram showed the parts of TDK CLI. This one shows time: what happens, in order, after you type tdk up. Knowing the order tells you where a start can stop, and which message to read when it does.

The sequence below follows the repo's documented behaviour: the host check, the drift check before Tilt starts, the Starlark generation at Tilt load time, readiness, and the JSON result. Some steps are summarised, so check them against the code and the docs before you rely on one exact message.

The sequence

sequenceDiagram
    autonumber
    actor Dev as Developer
    participant Agent as AI agent over MCP
    participant CLI as tdk CLI (TypeScript)
    participant Host as Host and container runtime
    participant Snap as Snapshots in .tdk-contract
    participant Tilt as Tilt
    participant Disc as Discovery (Starlark)
    participant Eng as Engine generators (Starlark)
    participant Dock as Docker
    participant Svc as Service containers

    Dev->>CLI: tdk up (or agent calls up)
    Agent->>CLI: up (MCP tool runs tdk up --json)

    CLI->>Host: check host type and container runtime
    alt canUp is false
        Host-->>CLI: no Docker, WebContainer, or Windows opt-in missing
        CLI-->>Dev: exit non-zero, tell the reason, do not spawn Tilt
    else canUp is true
        CLI->>Snap: compare generated files with saved snapshots
        alt a generated file was hand-edited
            Snap-->>CLI: drift found, name the file
            CLI-->>Dev: block the start, fix the source and retry
        else no drift
            CLI->>Tilt: spawn Tilt with the project Tiltfile
            Tilt->>Disc: load service.json files
            Disc-->>Tilt: resources, stacks, dependsOn
            Tilt->>Eng: generate per-service runtime files
            Eng-->>Tilt: write .autogenerated and service.yaml
            Tilt->>Dock: build images, start containers in order
            Dock->>Svc: start proxy, Postgres, services
            Svc-->>Tilt: health route answers
            Tilt-->>CLI: resources report ready or failed
            CLI-->>Agent: ok true, or ok false with errors
            CLI-->>Dev: TDK is up, with URLs and ports
        end
    end

    Note over Agent,CLI: The agent polls status until readiness.ready is true
    Agent->>CLI: status
    CLI-->>Agent: readiness ready, pending, or failures
    Dev->>CLI: tdk down
    CLI->>Tilt: stop resources
    Tilt->>Dock: stop and remove containers

The steps that can stop you

Four steps can stop a start, and each one tells you something different.

The host check. If canUp is false, the machine is the problem. No change to your project will help until the host has a working container runtime. The command exits without starting Tilt.

The drift check. A hand edit to a file under .autogenerated/ blocks the start and names the file. The fix is upstream: change service.json or the generator, then start again. This check runs before Tilt is spawned, so nothing has been built yet.

Readiness. up returns before the stack is ready, because a build can take longer than one command. The result tells you whether every resource is built, running, and healthy, or which one failed. tdk status --json answers the same question at any time.

The first failed resource. A failure in one service usually stops the ones that depend on it. Read the logs for the first failed resource, not the last. tdk logs --json --service <name> --tail 200 returns a bounded snapshot.

Where the agent fits

An agent does not replace this sequence. It calls the same commands through the MCP server. The useful part for the agent is the loop: call up, poll status until ready, read logs for any failure, then stop. The sequence above shows why the poll is needed. up returns before readiness.

Stopping cleanly

tdk down reverses the lifecycle: Tilt stops the resources, and Docker removes the containers. Run it when you finish. A stack left running keeps its ports, and the next up may refuse to start while an old Tilt still answers on its port.

Summary

One tdk up is a short chain of checks before any container starts: host, drift, then generation and readiness. Each check has its own message, and each message points at the fix. Read them in order, and most starts become a matter of reading the first line that failed.

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

tdk-cli — Sun, 18 Oct 2026 17:40:38 +0000

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.

Prompts for Claude Code and Codex That Work With TDK CLI: Build the App, Then Run the Stack

tdk-cli — Sun, 18 Oct 2026 17:37:25 +0000

Claude Code and Codex work inside your project folder, so they can read the code, run commands, and edit files. TDK CLI gives them a local stack they can control. The prompts below ask for an app shaped so TDK can describe and run it, and the steps after them connect the agent to the stack.

I have not run these prompts in Claude Code or Codex for this article, so check the output. The MCP setup for Codex comes from the TDK agent tooling docs. For Claude Code, follow that guide's own steps.

Before you start

Create the project with TDK first, so the agent starts from the same layout TDK expects:

tdk project --yes
tdk resource api --type backend -y
tdk resource web --type frontend -y

Confirm the machine can run the stack, and read the plan before the first start:

tdk doctor --json
tdk up main --dry-run

Connect the MCP server, so the agent can use the stack directly. For Codex, add this to .codex/config.toml in the project:

[mcp_servers.tdk]
command = "tdk"
args = ["mcp"]
cwd = "/absolute/path/to/your/tdk-project"

For Claude Code, follow the agent tooling guide. The working directory must be the project folder either way.

Prompt 1: start and check the stack

Use the TDK tools to check this project.
1. Call doctor. If canUp is false, stop and tell me why.
2. Call up for the api and web services.
3. Call status until readiness.ready is true, or until failures appear.
4. If a service fails, call logs for that service with tail 200 and quote the first error line.
Do not edit any file under .autogenerated/.
Report the status output, not a summary of it.

Why it works: it gives the agent a procedure with a clear finish line, and it asks for evidence.

Prompt 2: add a service without touching the generated files

Add a worker service called order-emails with TDK.
Run: tdk resource order-emails --type worker -y
Make it depend on the api service by adding it to dependsOn in its service.json.
Do not edit anything under .autogenerated/.
Then run tdk up main --dry-run and confirm the api starts before order-emails.
If the dry run shows an error, stop and report it.

Why it works: the dependency is declared, the generated files are off limits, and the agent checks the start order against the plan TDK prints.

Prompt 3: fix a failing service with a bounded loop

The api service is failing. Work on it this way:
1. Call logs for api with tail 200. Find the first error line.
2. Fix that error in the source under services/, not in generated files.
3. Call status until api is ready, or stop after three attempts.
4. After three failed attempts, stop and report what you tried and the latest log lines.
Do not change service.json ports or the health path without asking me.

Why it works: it limits retries, keeps the fix in the source, and stops before the agent starts changing configuration you have not approved.

Prompt 4: check the change before you accept it

Show me the list of files you changed, then the diff for each one.
Run the tests for the service you changed and paste the output.
Call status and confirm the service is ready after your change.
Tell me anything you did not verify.

Why it works: it turns "done" into a list you can read, and it asks for the gaps.

Prompt 5: stop cleanly

We are finished. Call down to stop the stack, then call status and confirm nothing is running.

Why it works: a stack left running holds ports for the next start, and the status call confirms the stop.

Rules to put in your project instructions

Add these to AGENTS.md or your Claude Code instructions, so every session follows them:

Start with doctor, then up, then status.
Never edit files under .autogenerated/.
Stop after three failed attempts and report.
Ask before changing ports, health paths, or secrets.
Call down when the task is finished.

Common problems

doctor says canUp is false. The machine cannot run the stack. The agent should stop there, not retry.
up returns, but nothing is ready. It returns before readiness. The agent must poll status.
The agent edits a generated file. The next generation overwrites it. Restate the rule, and check the drift output.
Two stacks fight over ports. Run down on the old one.

Summary

Give Claude Code and Codex a project created by TDK, connect the MCP server from the project folder, and use prompts that ask for a procedure, a finish line, a retry limit, and evidence. The agent does the typing. TDK keeps the stack in a shape it can check.