# dbt-labs/dbt-charts architecture

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

- Interactive diagram: https://gitdiagram.com/dbt-labs/dbt-charts
- Repository: https://github.com/dbt-labs/dbt-charts

## Overview

dbt Charts turns SQL queries and declarative YAML board definitions into interactive dashboards and reports. The principal workflow is authoring a board, validating or compiling it, executing its queries through a configured warehouse adapter, then rendering or serving the result. The CLI also exposes query, search, impact, and documentation workflows; agent clients use an MCP interface over the agent API. Paths and README capabilities identify these subsystems, but sampled source is incomplete, so uncertain internal call links are omitted.

Main entry points: [`src/dbt_charts/cli/main.py`](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/cli/main.py) (dct CLI), [`src/dbt_charts/core/compile/compiler.py`](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/compile/compiler.py) (Board compiler), [`src/dbt_charts/core/registered_views/render_pipeline.py`](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/registered_views/render_pipeline.py) (Registered views), [`src/dbt_charts/agent_api/__init__.py`](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/agent_api/__init__.py) (Agent API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["dct CLI<br/>[main.py]"]
  node_http["HTTP server<br/>[server.py]"]
end

subgraph group_author["Board processing"]
  node_compiler["Board compiler<br/>[compiler.py]"]
  node_parser["Board parser<br/>[parser.py]"]
  node_normalizer["Normalization<br/>[charts.py]"]
  node_resolver["Chart resolution<br/>[__init__.py]"]
  node_validator["Query validator<br/>[query_validator.py]"]
end

subgraph group_runtime["Query and rendering"]
  node_executor["Query executor<br/>[executor.py]"]
  node_adapters["Warehouse adapters"]
  node_renderer["Chart renderer<br/>[emitter.py]"]
  node_serve_pipeline["Registered views<br/>[render_pipeline.py]"]
end

subgraph group_assist["Agent workflows"]
  node_agent_api["Agent API<br/>[__init__.py]"]
  node_mcp["MCP server<br/>[server.py]"]
  node_search["Board search<br/>[search.py]"]
  node_impact["Column impact<br/>[impact.py]"]
end

subgraph group_integrations["External systems"]
  node_warehouse[("SQL warehouse")]
  node_cloud["Cloud platform"]
end

node_engineer(("Engineer"))
node_board["Board YAML"]
node_result["Dashboard output"]

node_engineer -->|"invokes"| node_cli
node_engineer -->|"authors"| node_board
node_board -->|"compiles"| node_compiler
node_compiler -->|"parses"| node_parser
node_compiler -->|"normalizes"| node_normalizer
node_compiler -->|"resolves"| node_resolver
node_cli -->|"validates or renders"| node_compiler
node_cli -->|"runs queries"| node_executor
node_cli -->|"renders formats"| node_renderer
node_executor -->|"dispatches queries"| node_adapters
node_adapters -->|"executes SQL"| node_warehouse
node_cli -->|"checks SQL"| node_validator
node_http -->|"requests rendering"| node_serve_pipeline
node_serve_pipeline -->|"compiles view"| node_compiler
node_serve_pipeline -->|"executes and renders"| node_executor
node_renderer -->|"emits dashboard"| node_result
node_engineer -->|"previews boards"| node_http
node_cli -->|"exposes agent verbs"| node_agent_api
node_mcp -->|"dispatches tools"| node_agent_api
node_agent_api -->|"searches boards"| node_search
node_agent_api -->|"traces columns"| node_impact
node_cloud -.->|"uses render API"| node_serve_pipeline

click node_cli "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/cli/main.py"
click node_http "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/serve/server.py"
click node_compiler "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/compile/compiler.py"
click node_parser "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/compile/parse/parser.py"
click node_normalizer "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/compile/normalize/charts.py"
click node_resolver "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/compile/resolve/chart/__init__.py"
click node_validator "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/inspect/query_validator.py"
click node_executor "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/execute/executor.py"
click node_adapters "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/execute/adapters/adapter_registry.py"
click node_renderer "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/render/chart/emitter.py"
click node_serve_pipeline "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/registered_views/render_pipeline.py"
click node_agent_api "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/agent_api/__init__.py"
click node_mcp "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/ai/mcp/server.py"
click node_search "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/agent_api/search.py"
click node_impact "https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/agent_api/impact.py"

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_http toneBlue
class node_compiler,node_parser,node_normalizer,node_resolver,node_validator toneAmber
class node_executor,node_adapters,node_renderer,node_serve_pipeline toneMint
class node_agent_api,node_mcp,node_search,node_impact toneRose
class node_warehouse,node_cloud,node_engineer,node_board,node_result toneIndigo
```

## Components

### User interfaces

- [dct CLI](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/cli/main.py): `src/dbt_charts/cli/main.py`
- [HTTP server](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/serve/server.py): `src/dbt_charts/core/serve/server.py`

### Board processing

- [Board compiler](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/compile/compiler.py): `src/dbt_charts/core/compile/compiler.py`
- [Board parser](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/compile/parse/parser.py): `src/dbt_charts/core/compile/parse/parser.py`
- [Normalization](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/compile/normalize/charts.py): `src/dbt_charts/core/compile/normalize/charts.py`
- [Chart resolution](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/compile/resolve/chart/__init__.py): `src/dbt_charts/core/compile/resolve/chart/__init__.py`
- [Query validator](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/inspect/query_validator.py): `src/dbt_charts/core/inspect/query_validator.py`

### Query and rendering

- [Query executor](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/execute/executor.py): `src/dbt_charts/core/execute/executor.py`
- [Warehouse adapters](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/execute/adapters/adapter_registry.py): `src/dbt_charts/core/execute/adapters/adapter_registry.py`
- [Chart renderer](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/render/chart/emitter.py): `src/dbt_charts/core/render/chart/emitter.py`
- [Registered views](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/core/registered_views/render_pipeline.py): `src/dbt_charts/core/registered_views/render_pipeline.py`

### Agent workflows

- [Agent API](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/agent_api/__init__.py): `src/dbt_charts/agent_api/__init__.py`
- [MCP server](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/ai/mcp/server.py): `src/dbt_charts/ai/mcp/server.py`
- [Board search](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/agent_api/search.py): `src/dbt_charts/agent_api/search.py`
- [Column impact](https://github.com/dbt-labs/dbt-charts/blob/main/src/dbt_charts/agent_api/impact.py): `src/dbt_charts/agent_api/impact.py`

### External systems

- **SQL warehouse**
- **Cloud platform**

### Other components

- **Engineer**
- **Board YAML**
- **Dashboard output**

## Connections

- Engineer → dct CLI: invokes
- Engineer → Board YAML: authors
- Board YAML → Board compiler: compiles
- Board compiler → Board parser: parses
- Board compiler → Normalization: normalizes
- Board compiler → Chart resolution: resolves
- dct CLI → Board compiler: validates or renders
- dct CLI → Query executor: runs queries
- dct CLI → Chart renderer: renders formats
- Query executor → Warehouse adapters: dispatches queries
- Warehouse adapters → SQL warehouse: executes SQL
- dct CLI → Query validator: checks SQL
- HTTP server → Registered views: requests rendering
- Registered views → Board compiler: compiles view
- Registered views → Query executor: executes and renders
- Chart renderer → Dashboard output: emits dashboard
- Engineer → HTTP server: previews boards
- dct CLI → Agent API: exposes agent verbs
- MCP server → Agent API: dispatches tools
- Agent API → Board search: searches boards
- Agent API → Column impact: traces columns
- Cloud platform → Registered views: uses render API