# tilt-dev/tilt architecture

> Architecture diagram of the GitHub repository tilt-dev/tilt, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tilt-dev/tilt
- Repository: https://github.com/tilt-dev/tilt

## Overview

Tilt is a local development orchestrator for multi-service applications. A user starts it with `tilt up`; Tiltfile configuration describes resources, and Tilt watches files, builds images or commands, and updates Kubernetes or Docker Compose environments. Controllers and shared engine state coordinate that work, while the local HUD and web client expose status and logs. The README documents the end-to-end development loop; sampled excerpts show selected controller, state, and server behavior, but not all subsystem wiring.

Main entry points: [`internal/cli/up.go`](https://github.com/tilt-dev/tilt/blob/master/internal/cli/up.go) (Tilt CLI), [`internal/engine/buildcontrol/build_and_deployer.go`](https://github.com/tilt-dev/tilt/blob/master/internal/engine/buildcontrol/build_and_deployer.go) (Build and deploy), [`internal/store/engine_state.go`](https://github.com/tilt-dev/tilt/blob/master/internal/store/engine_state.go) (Engine state), [`internal/hud/server/server.go`](https://github.com/tilt-dev/tilt/blob/master/internal/hud/server/server.go) (HUD server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entry"]
  node_tiltcli["Tilt CLI<br/>[up.go]"]
end

subgraph group_config["Configuration and state"]
  node_tiltfile["Tiltfile evaluation<br/>[tiltfile.go]"]
  node_engine[("Engine state<br/>[engine_state.go]")]
end

subgraph group_runtime["Build and runtime"]
  node_filewatch["File watching<br/>[controller.go]"]
  node_buildcontroller["Build controller<br/>[buildcontroller.go]"]
  node_builddeploy["Build and deploy"]
  node_docker["Docker client<br/>[client.go]"]
  node_compose["Compose client<br/>[client.go]"]
  node_k8s["Kubernetes client<br/>[client.go]"]
  node_cmdcontroller["Command controller<br/>[controller.go]"]
  node_localserver["Local process manager"]
  node_podlogs["Pod log streams"]
end

subgraph group_experience["Status and interface"]
  node_hudserver["HUD server<br/>[server.go]"]
  node_webclient["Web client state<br/>[HudState.tsx]"]
  node_logstore["Web log store<br/>[LogStore.ts]"]
end

node_developer(("Developer"))
node_browser(("Browser user"))
node_cluster{{"Kubernetes cluster"}}
node_composeenv{{"Compose environment"}}

node_developer -->|"runs tilt up"| node_tiltcli
node_tiltcli -.->|"starts configuration"| node_tiltfile
node_tiltcli -.->|"dispatches actions"| node_engine
node_tiltcli -->|"invokes CLI"| node_tiltfile
node_filewatch -->|"dispatches updates"| node_engine
node_buildcontroller -->|"reads build state"| node_engine
node_buildcontroller -->|"runs builds"| node_builddeploy
node_builddeploy -.->|"builds images"| node_docker
node_builddeploy -.->|"deploys services"| node_compose
node_builddeploy -.->|"applies workloads"| node_k8s
node_docker -.->|"provides images"| node_cluster
node_compose -.->|"updates services"| node_composeenv
node_k8s -.->|"manages resources"| node_cluster
node_cmdcontroller -->|"starts commands"| node_localserver
node_podlogs -->|"reads pod logs"| node_k8s
node_hudserver -->|"reads and dispatches"| node_engine
node_browser -.->|"requests HUD"| node_hudserver
node_webclient -->|"uses log state"| node_logstore
node_hudserver -.->|"serves interface"| node_webclient

click node_tiltcli "https://github.com/tilt-dev/tilt/blob/master/internal/cli/up.go"
click node_tiltfile "https://github.com/tilt-dev/tilt/blob/master/internal/tiltfile/tiltfile.go"
click node_engine "https://github.com/tilt-dev/tilt/blob/master/internal/store/engine_state.go"
click node_filewatch "https://github.com/tilt-dev/tilt/blob/master/internal/controllers/core/filewatch/controller.go"
click node_buildcontroller "https://github.com/tilt-dev/tilt/blob/master/internal/engine/buildcontroller.go"
click node_builddeploy "https://github.com/tilt-dev/tilt/blob/master/internal/engine/buildcontrol/build_and_deployer.go"
click node_docker "https://github.com/tilt-dev/tilt/blob/master/internal/docker/client.go"
click node_compose "https://github.com/tilt-dev/tilt/blob/master/internal/dockercompose/client.go"
click node_k8s "https://github.com/tilt-dev/tilt/blob/master/internal/k8s/client.go"
click node_cmdcontroller "https://github.com/tilt-dev/tilt/blob/master/internal/controllers/core/cmd/controller.go"
click node_localserver "https://github.com/tilt-dev/tilt/blob/master/internal/engine/local/servercontroller.go"
click node_podlogs "https://github.com/tilt-dev/tilt/blob/master/internal/controllers/core/podlogstream/podlogstreamcontroller.go"
click node_hudserver "https://github.com/tilt-dev/tilt/blob/master/internal/hud/server/server.go"
click node_webclient "https://github.com/tilt-dev/tilt/blob/master/web/src/HudState.tsx"
click node_logstore "https://github.com/tilt-dev/tilt/blob/master/web/src/LogStore.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tiltcli,node_browser toneBlue
class node_tiltfile,node_engine toneAmber
class node_filewatch,node_buildcontroller,node_builddeploy,node_docker,node_compose,node_k8s,node_cmdcontroller,node_localserver,node_podlogs toneMint
class node_hudserver,node_webclient,node_logstore toneRose
class node_developer,node_cluster,node_composeenv toneIndigo
```

## Components

### User entry

- [Tilt CLI](https://github.com/tilt-dev/tilt/blob/master/internal/cli/up.go): `internal/cli/up.go`

### Configuration and state

- [Tiltfile evaluation](https://github.com/tilt-dev/tilt/blob/master/internal/tiltfile/tiltfile.go): `internal/tiltfile/tiltfile.go`
- [Engine state](https://github.com/tilt-dev/tilt/blob/master/internal/store/engine_state.go): `internal/store/engine_state.go`

### Build and runtime

- [File watching](https://github.com/tilt-dev/tilt/blob/master/internal/controllers/core/filewatch/controller.go): `internal/controllers/core/filewatch/controller.go`
- [Build controller](https://github.com/tilt-dev/tilt/blob/master/internal/engine/buildcontroller.go): `internal/engine/buildcontroller.go`
- [Build and deploy](https://github.com/tilt-dev/tilt/blob/master/internal/engine/buildcontrol/build_and_deployer.go): `internal/engine/buildcontrol/build_and_deployer.go`
- [Docker client](https://github.com/tilt-dev/tilt/blob/master/internal/docker/client.go): `internal/docker/client.go`
- [Compose client](https://github.com/tilt-dev/tilt/blob/master/internal/dockercompose/client.go): `internal/dockercompose/client.go`
- [Kubernetes client](https://github.com/tilt-dev/tilt/blob/master/internal/k8s/client.go): `internal/k8s/client.go`
- [Command controller](https://github.com/tilt-dev/tilt/blob/master/internal/controllers/core/cmd/controller.go): `internal/controllers/core/cmd/controller.go`
- [Local process manager](https://github.com/tilt-dev/tilt/blob/master/internal/engine/local/servercontroller.go): `internal/engine/local/servercontroller.go`
- [Pod log streams](https://github.com/tilt-dev/tilt/blob/master/internal/controllers/core/podlogstream/podlogstreamcontroller.go): `internal/controllers/core/podlogstream/podlogstreamcontroller.go`

### Status and interface

- [HUD server](https://github.com/tilt-dev/tilt/blob/master/internal/hud/server/server.go): `internal/hud/server/server.go`
- [Web client state](https://github.com/tilt-dev/tilt/blob/master/web/src/HudState.tsx): `web/src/HudState.tsx`
- [Web log store](https://github.com/tilt-dev/tilt/blob/master/web/src/LogStore.ts): `web/src/LogStore.ts`

### Other components

- **Developer**
- **Browser user**
- **Kubernetes cluster**
- **Compose environment**

## Connections

- Developer → Tilt CLI: runs tilt up (evidence: `README.md`)
- Tilt CLI → Tiltfile evaluation: starts configuration
- Tilt CLI → Engine state: dispatches actions
- Tilt CLI → Tiltfile evaluation: invokes CLI
- File watching → Engine state: dispatches updates (evidence: `internal/controllers/core/filewatch/controller.go`)
- Build controller → Engine state: reads build state (evidence: `internal/engine/buildcontroller.go`)
- Build controller → Build and deploy: runs builds (evidence: `internal/engine/buildcontroller.go`)
- Build and deploy → Docker client: builds images
- Build and deploy → Compose client: deploys services
- Build and deploy → Kubernetes client: applies workloads
- Docker client → Kubernetes cluster: provides images
- Compose client → Compose environment: updates services
- Kubernetes client → Kubernetes cluster: manages resources
- Command controller → Local process manager: starts commands (evidence: `internal/controllers/core/cmd/controller.go`)
- Pod log streams → Kubernetes client: reads pod logs (evidence: `internal/controllers/core/podlogstream/podlogstreamcontroller.go`)
- HUD server → Engine state: reads and dispatches (evidence: `internal/hud/server/server.go`)
- Browser user → HUD server: requests HUD
- Web client state → Web log store: uses log state (evidence: `web/src/HudState.tsx`)
- HUD server → Web client state: serves interface
