# gruntwork-io/terragrunt architecture

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

- Interactive diagram: https://gitdiagram.com/gruntwork-io/terragrunt
- Repository: https://github.com/gruntwork-io/terragrunt

## Overview

Terragrunt orchestrates Terraform/OpenTofu configurations: a user invokes a CLI command, configuration is parsed and units discovered, dependencies determine execution order, and units run with downloaded sources and an IaC engine. Results and outputs support downstream units. The repository also exposes catalog, MCP, remote-state bootstrap, and provider-cache capabilities. The README identifies the product but does not detail these subsystems; paths and relationships below use the supplied tree and sampled source, so unsampled wiring is left out.

Main entry points: [`internal/cli/commands`](https://github.com/gruntwork-io/terragrunt/tree/main/internal/cli/commands) (CLI commands), [`internal/runner/run/run.go`](https://github.com/gruntwork-io/terragrunt/blob/main/internal/runner/run/run.go) (IaC command execution), [`internal/runner`](https://github.com/gruntwork-io/terragrunt/tree/main/internal/runner) (Run orchestration), [`main.go`](https://github.com/gruntwork-io/terragrunt/blob/main/main.go) (CLI entry point)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and tools"]
  node_main["CLI entry point<br/>[main.go]"]
  node_app["Command application<br/>[app.go]"]
  node_commands["CLI commands"]
end

subgraph group_config["Configuration and discovery"]
  node_config_parse["HCL configuration"]
  node_discovery["Unit discovery"]
  node_components["Unit components"]
end

subgraph group_execution["Orchestration and execution"]
  node_runner["Run orchestration"]
  node_queue["Dependency queue<br/>[queue.go]"]
  node_unit_runner["Unit runner<br/>[unit_runner.go]"]
  node_run["IaC command execution<br/>[run.go]"]
  node_source_getter["Source retrieval"]
  node_cas[("Source content store")]
end

subgraph group_integrations["State and cloud integrations"]
  node_remote_state["Remote state"]
  node_cloud_backends["Cloud backends"]
  node_backend_commands["Backend commands"]
end

subgraph group_services["Catalog and services"]
  node_catalog["Component catalog"]
  node_mcp["MCP server"]
  node_provider_cache["Provider cache server<br/>[server.go]"]
end

node_operator(("Infrastructure engineer"))
node_iac_engine["Terraform/OpenTofu"]
node_cloud_apis["Cloud APIs"]
node_engine_plugin["Engine plugin"]

node_operator -->|"invokes"| node_main
node_main -->|"starts"| node_app
node_app -->|"dispatches"| node_commands
node_commands -->|"loads configuration"| node_config_parse
node_config_parse -->|"provides configuration"| node_discovery
node_discovery -->|"discovers units"| node_components
node_commands -->|"starts runs"| node_runner
node_runner -->|"schedules dependencies"| node_queue
node_runner -->|"dispatches units"| node_unit_runner
node_unit_runner -->|"executes unit"| node_run
node_run -->|"retrieves source"| node_source_getter
node_source_getter -->|"stores content"| node_cas
node_run -->|"runs IaC command"| node_iac_engine
node_run -->|"reads outputs"| node_remote_state
node_remote_state -->|"uses backend"| node_cloud_backends
node_cloud_backends -->|"reads and writes state"| node_cloud_apis
node_backend_commands -->|"manages backend"| node_cloud_apis
node_commands -->|"serves catalog"| node_catalog
node_commands -->|"starts server"| node_mcp
node_commands -->|"starts cache"| node_provider_cache
node_commands -.->|"launches plugin"| node_engine_plugin

click node_main "https://github.com/gruntwork-io/terragrunt/blob/main/main.go"
click node_app "https://github.com/gruntwork-io/terragrunt/blob/main/internal/cli/app.go"
click node_commands "https://github.com/gruntwork-io/terragrunt/tree/main/internal/cli/commands"
click node_config_parse "https://github.com/gruntwork-io/terragrunt/tree/main/pkg/config"
click node_discovery "https://github.com/gruntwork-io/terragrunt/tree/main/internal/discovery"
click node_components "https://github.com/gruntwork-io/terragrunt/tree/main/internal/component"
click node_runner "https://github.com/gruntwork-io/terragrunt/tree/main/internal/runner"
click node_queue "https://github.com/gruntwork-io/terragrunt/blob/main/internal/queue/queue.go"
click node_unit_runner "https://github.com/gruntwork-io/terragrunt/blob/main/internal/runner/unit_runner.go"
click node_run "https://github.com/gruntwork-io/terragrunt/blob/main/internal/runner/run/run.go"
click node_source_getter "https://github.com/gruntwork-io/terragrunt/tree/main/internal/getter"
click node_cas "https://github.com/gruntwork-io/terragrunt/tree/main/internal/cas"
click node_remote_state "https://github.com/gruntwork-io/terragrunt/tree/main/internal/remotestate"
click node_cloud_backends "https://github.com/gruntwork-io/terragrunt/tree/main/internal/remotestate/backend"
click node_catalog "https://github.com/gruntwork-io/terragrunt/tree/main/internal/services/catalog"
click node_mcp "https://github.com/gruntwork-io/terragrunt/tree/main/internal/cli/commands/mcp"
click node_provider_cache "https://github.com/gruntwork-io/terragrunt/blob/main/internal/tf/cache/server.go"
click node_backend_commands "https://github.com/gruntwork-io/terragrunt/tree/main/internal/cli/commands/backend"

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_main,node_app,node_commands toneBlue
class node_config_parse,node_discovery,node_components toneAmber
class node_runner,node_queue,node_unit_runner,node_run,node_source_getter,node_cas,node_cloud_apis toneMint
class node_remote_state,node_cloud_backends,node_backend_commands toneRose
class node_catalog,node_mcp,node_provider_cache,node_operator,node_iac_engine,node_engine_plugin toneIndigo
```

## Components

### CLI and tools

- [CLI entry point](https://github.com/gruntwork-io/terragrunt/blob/main/main.go): `main.go`
- [Command application](https://github.com/gruntwork-io/terragrunt/blob/main/internal/cli/app.go): `internal/cli/app.go`
- [CLI commands](https://github.com/gruntwork-io/terragrunt/tree/main/internal/cli/commands): `internal/cli/commands`

### Configuration and discovery

- [HCL configuration](https://github.com/gruntwork-io/terragrunt/tree/main/pkg/config): `pkg/config`
- [Unit discovery](https://github.com/gruntwork-io/terragrunt/tree/main/internal/discovery): `internal/discovery`
- [Unit components](https://github.com/gruntwork-io/terragrunt/tree/main/internal/component): `internal/component`

### Orchestration and execution

- [Run orchestration](https://github.com/gruntwork-io/terragrunt/tree/main/internal/runner): `internal/runner`
- [Dependency queue](https://github.com/gruntwork-io/terragrunt/blob/main/internal/queue/queue.go): `internal/queue/queue.go`
- [Unit runner](https://github.com/gruntwork-io/terragrunt/blob/main/internal/runner/unit_runner.go): `internal/runner/unit_runner.go`
- [IaC command execution](https://github.com/gruntwork-io/terragrunt/blob/main/internal/runner/run/run.go): `internal/runner/run/run.go`
- [Source retrieval](https://github.com/gruntwork-io/terragrunt/tree/main/internal/getter): `internal/getter`
- [Source content store](https://github.com/gruntwork-io/terragrunt/tree/main/internal/cas): `internal/cas`

### State and cloud integrations

- [Remote state](https://github.com/gruntwork-io/terragrunt/tree/main/internal/remotestate): `internal/remotestate`
- [Cloud backends](https://github.com/gruntwork-io/terragrunt/tree/main/internal/remotestate/backend): `internal/remotestate/backend`
- [Backend commands](https://github.com/gruntwork-io/terragrunt/tree/main/internal/cli/commands/backend): `internal/cli/commands/backend`

### Catalog and services

- [Component catalog](https://github.com/gruntwork-io/terragrunt/tree/main/internal/services/catalog): `internal/services/catalog`
- [MCP server](https://github.com/gruntwork-io/terragrunt/tree/main/internal/cli/commands/mcp): `internal/cli/commands/mcp`
- [Provider cache server](https://github.com/gruntwork-io/terragrunt/blob/main/internal/tf/cache/server.go): `internal/tf/cache/server.go`

### Other components

- **Infrastructure engineer**
- **Terraform/OpenTofu**
- **Cloud APIs**
- **Engine plugin**

## Connections

- Infrastructure engineer → CLI entry point: invokes
- CLI entry point → Command application: starts
- Command application → CLI commands: dispatches
- CLI commands → HCL configuration: loads configuration
- HCL configuration → Unit discovery: provides configuration
- Unit discovery → Unit components: discovers units
- CLI commands → Run orchestration: starts runs
- Run orchestration → Dependency queue: schedules dependencies
- Run orchestration → Unit runner: dispatches units
- Unit runner → IaC command execution: executes unit
- IaC command execution → Source retrieval: retrieves source
- Source retrieval → Source content store: stores content
- IaC command execution → Terraform/OpenTofu: runs IaC command
- IaC command execution → Remote state: reads outputs
- Remote state → Cloud backends: uses backend
- Cloud backends → Cloud APIs: reads and writes state
- Backend commands → Cloud APIs: manages backend
- CLI commands → Component catalog: serves catalog
- CLI commands → MCP server: starts server
- CLI commands → Provider cache server: starts cache
- CLI commands → Engine plugin: launches plugin