# docker/compose architecture

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

- Interactive diagram: https://gitdiagram.com/docker/compose
- Repository: https://github.com/docker/compose

## Overview

Docker Compose is a Docker CLI plugin for defining and operating multi-container applications from Compose files. The principal workflow is: a user supplies a Compose model and runs `docker compose up`; the CLI loads project configuration, then the Compose runtime creates and starts its services through the Docker Engine, with progress and results displayed to the user. The repository also supports lifecycle commands, builds and image operations, logs and interactive container operations, file watching, provider plugins, and relay services. Several command implementations are unsampled, so uncertain runtime links are dashed.

Main entry points: [`pkg/compose/compose.go`](https://github.com/docker/compose/blob/main/pkg/compose/compose.go) (Compose service runtime), [`cmd/compose/compose.go`](https://github.com/docker/compose/blob/main/cmd/compose/compose.go) (CLI commands), [`internal/projectloader`](https://github.com/docker/compose/tree/main/internal/projectloader) (Project loading), [`pkg/bridge/convert.go`](https://github.com/docker/compose/blob/main/pkg/bridge/convert.go) (Model conversion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and display"]
  node_cli["CLI commands<br/>[compose.go]"]
  node_display["Progress display<br/>[tty_layout.go]"]
  node_format["Output formatting<br/>[shortcut.go]"]
end

subgraph group_model["Project modeling"]
  node_project["Project loading"]
  node_bridge["Model conversion<br/>[convert.go]"]
  node_depgraph["Service dependencies<br/>[depgraph.go]"]
end

subgraph group_runtime["Compose runtime"]
  node_runtime["Compose service runtime<br/>[compose.go]"]
  node_plan["Service planning<br/>[plan.go]"]
  node_reconcile["State reconciliation<br/>[reconcile.go]"]
  node_containers["Container lifecycle"]
  node_watch["File watching<br/>[watch.go]"]
end

subgraph group_ops["Container and image operations"]
  node_build["Image building<br/>[build.go]"]
  node_images["Image operations<br/>[images.go]"]
  node_oci["OCI registry operations<br/>[push.go]"]
  node_containerops["Container utilities<br/>[cp.go]"]
  node_logs["Logs and attach<br/>[attach_service.go]"]
end

subgraph group_extensions["Extensions and integrations"]
  node_providers["Provider plugins<br/>[plugins.go]"]
  node_relay["Network relay<br/>[relay.go]"]
  node_desktop["Desktop integration<br/>[client.go]"]
  node_dryrun["Dry-run client<br/>[dryrunclient.go]"]
end

node_user(("Compose user"))
node_engine[("Docker Engine")]

node_user -->|"runs command"| node_cli
node_cli -.->|"loads model"| node_project
node_project -.->|"converts model"| node_bridge
node_bridge -.->|"resolves dependencies"| node_depgraph
node_cli -.->|"dispatches operation"| node_runtime
node_runtime -.->|"plans services"| node_plan
node_runtime -.->|"reconciles state"| node_reconcile
node_runtime -.->|"manages containers"| node_containers
node_runtime -.->|"builds images"| node_build
node_runtime -.->|"operates on images"| node_images
node_runtime -.->|"pushes images"| node_oci
node_runtime -.->|"watches files"| node_watch
node_cli -.->|"dispatches utilities"| node_containerops
node_cli -.->|"dispatches logs"| node_logs
node_runtime -.->|"uses engine backend"| node_engine
node_containers -.->|"creates containers"| node_engine
node_runtime -.->|"reports progress"| node_display
node_cli -->|"configures output"| node_format
node_providers -->|"ensures relay"| node_relay
node_desktop -.->|"connects locally"| node_engine
node_cli -.->|"uses dry-run client"| node_dryrun

click node_cli "https://github.com/docker/compose/blob/main/cmd/compose/compose.go"
click node_display "https://github.com/docker/compose/blob/main/cmd/display/tty_layout.go"
click node_format "https://github.com/docker/compose/blob/main/cmd/formatter/shortcut.go"
click node_project "https://github.com/docker/compose/tree/main/internal/projectloader"
click node_bridge "https://github.com/docker/compose/blob/main/pkg/bridge/convert.go"
click node_depgraph "https://github.com/docker/compose/blob/main/internal/depgraph/depgraph.go"
click node_runtime "https://github.com/docker/compose/blob/main/pkg/compose/compose.go"
click node_plan "https://github.com/docker/compose/blob/main/pkg/compose/plan.go"
click node_reconcile "https://github.com/docker/compose/blob/main/pkg/compose/reconcile.go"
click node_containers "https://github.com/docker/compose/blob/main/pkg/compose/service_containers.go"
click node_watch "https://github.com/docker/compose/blob/main/pkg/compose/watch.go"
click node_build "https://github.com/docker/compose/blob/main/pkg/compose/build.go"
click node_images "https://github.com/docker/compose/blob/main/internal/images/images.go"
click node_oci "https://github.com/docker/compose/blob/main/internal/oci/push.go"
click node_containerops "https://github.com/docker/compose/blob/main/internal/containerops/cp.go"
click node_logs "https://github.com/docker/compose/blob/main/internal/logstream/attach_service.go"
click node_providers "https://github.com/docker/compose/blob/main/internal/provider/plugins.go"
click node_relay "https://github.com/docker/compose/blob/main/internal/relay/relay.go"
click node_desktop "https://github.com/docker/compose/blob/main/internal/desktop/client.go"
click node_dryrun "https://github.com/docker/compose/blob/main/pkg/dryrun/dryrunclient.go"

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_cli,node_display,node_format,node_user toneBlue
class node_project,node_bridge,node_depgraph,node_engine toneAmber
class node_runtime,node_plan,node_reconcile,node_containers,node_watch toneMint
class node_build,node_images,node_oci,node_containerops,node_logs toneRose
class node_providers,node_relay,node_desktop,node_dryrun toneIndigo
```

## Components

### CLI and display

- [CLI commands](https://github.com/docker/compose/blob/main/cmd/compose/compose.go): `cmd/compose/compose.go`
- [Progress display](https://github.com/docker/compose/blob/main/cmd/display/tty_layout.go): `cmd/display/tty_layout.go`
- [Output formatting](https://github.com/docker/compose/blob/main/cmd/formatter/shortcut.go): `cmd/formatter/shortcut.go`

### Project modeling

- [Project loading](https://github.com/docker/compose/tree/main/internal/projectloader): `internal/projectloader`
- [Model conversion](https://github.com/docker/compose/blob/main/pkg/bridge/convert.go): `pkg/bridge/convert.go`
- [Service dependencies](https://github.com/docker/compose/blob/main/internal/depgraph/depgraph.go): `internal/depgraph/depgraph.go`

### Compose runtime

- [Compose service runtime](https://github.com/docker/compose/blob/main/pkg/compose/compose.go): `pkg/compose/compose.go`
- [Service planning](https://github.com/docker/compose/blob/main/pkg/compose/plan.go): `pkg/compose/plan.go`
- [State reconciliation](https://github.com/docker/compose/blob/main/pkg/compose/reconcile.go): `pkg/compose/reconcile.go`
- [Container lifecycle](https://github.com/docker/compose/blob/main/pkg/compose/service_containers.go): `pkg/compose/service_containers.go`
- [File watching](https://github.com/docker/compose/blob/main/pkg/compose/watch.go): `pkg/compose/watch.go`

### Container and image operations

- [Image building](https://github.com/docker/compose/blob/main/pkg/compose/build.go): `pkg/compose/build.go`
- [Image operations](https://github.com/docker/compose/blob/main/internal/images/images.go): `internal/images/images.go`
- [OCI registry operations](https://github.com/docker/compose/blob/main/internal/oci/push.go): `internal/oci/push.go`
- [Container utilities](https://github.com/docker/compose/blob/main/internal/containerops/cp.go): `internal/containerops/cp.go`
- [Logs and attach](https://github.com/docker/compose/blob/main/internal/logstream/attach_service.go): `internal/logstream/attach_service.go`

### Extensions and integrations

- [Provider plugins](https://github.com/docker/compose/blob/main/internal/provider/plugins.go): `internal/provider/plugins.go`
- [Network relay](https://github.com/docker/compose/blob/main/internal/relay/relay.go): `internal/relay/relay.go`
- [Desktop integration](https://github.com/docker/compose/blob/main/internal/desktop/client.go): `internal/desktop/client.go`
- [Dry-run client](https://github.com/docker/compose/blob/main/pkg/dryrun/dryrunclient.go): `pkg/dryrun/dryrunclient.go`

### Other components

- **Compose user**
- **Docker Engine**

## Connections

- Compose user → CLI commands: runs command (evidence: `README.md`)
- CLI commands → Project loading: loads model
- Project loading → Model conversion: converts model
- Model conversion → Service dependencies: resolves dependencies
- CLI commands → Compose service runtime: dispatches operation
- Compose service runtime → Service planning: plans services
- Compose service runtime → State reconciliation: reconciles state
- Compose service runtime → Container lifecycle: manages containers
- Compose service runtime → Image building: builds images
- Compose service runtime → Image operations: operates on images
- Compose service runtime → OCI registry operations: pushes images
- Compose service runtime → File watching: watches files
- CLI commands → Container utilities: dispatches utilities
- CLI commands → Logs and attach: dispatches logs
- Compose service runtime → Docker Engine: uses engine backend
- Container lifecycle → Docker Engine: creates containers
- Compose service runtime → Progress display: reports progress
- CLI commands → Output formatting: configures output (evidence: `cmd/compose/compose.go`)
- Provider plugins → Network relay: ensures relay (evidence: `internal/provider/plugins.go`)
- Desktop integration → Docker Engine: connects locally
- CLI commands → Dry-run client: uses dry-run client
