# djlemkes/dbt-diagrams architecture

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

- Interactive diagram: https://gitdiagram.com/djlemkes/dbt-diagrams
- Repository: https://github.com/djlemkes/dbt-diagrams

## Overview

dbt-diagrams is a Python CLI that turns dbt manifest and optional catalog artifacts into Mermaid ERDs, embeds diagrams and general Mermaid blocks in dbt docs, and can export diagrams as Markdown, Mermaid, or SVG. The main workflow is artifact validation, model/relationship construction, Mermaid generation, then file output or docs integration and serving. The graph reflects the sampled CLI, domain, validation, Mermaid, and writer code; README-described capabilities are included, while the REST API is omitted because its implementation is commented out.

Main entry points: [`dbt_diagrams/cli.py`](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/cli.py) (CLI commands), [`dbt_diagrams/mermaid.py`](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/mermaid.py) (ERD construction), [`dbt_diagrams/output_writers.py`](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/output_writers.py) (File output writers), [`dbt_diagrams/input_validators.py`](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/input_validators.py) (Artifact validation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CLI workflow"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_dbt_docs["dbt docs command"]
  node_artifacts["dbt artifacts"]
end

subgraph group_erd["ERD generation"]
  node_validation["Artifact validation"]
  node_domain["ERD domain models<br/>[domain.py]"]
  node_erd_builder["ERD construction<br/>[mermaid.py]"]
end

subgraph group_docs["dbt docs integration"]
  node_mermaid_docs["Docs Mermaid insertion<br/>[mermaid.py]"]
  node_html_integration["Mermaid HTML integration<br/>[mermaid.py]"]
  node_generated_docs["Generated dbt docs"]
  node_docs_server["Docs server<br/>[cli.py]"]
end

subgraph group_render["Output rendering"]
  node_mermaid_output["Mermaid diagram text<br/>[mermaid.py]"]
  node_output_writers["File output writers<br/>[output_writers.py]"]
  node_svg_renderer["SVG browser rendering<br/>[output_writers.py]"]
  node_output_files["Exported diagram files"]
end

node_user(("dbt project user"))

node_user -->|"runs"| node_cli
node_dbt_docs -->|"generates"| node_artifacts
node_user -->|"provides"| node_artifacts
node_cli -->|"invokes"| node_dbt_docs
node_cli -->|"validates"| node_validation
node_cli -->|"requests ERDs"| node_erd_builder
node_erd_builder -->|"reads artifacts"| node_validation
node_erd_builder -->|"builds models"| node_domain
node_erd_builder -->|"generates"| node_mermaid_output
node_cli -->|"selects format"| node_output_writers
node_output_writers -->|"renders SVG"| node_svg_renderer
node_output_writers -->|"writes"| node_output_files
node_cli -->|"embeds ERDs"| node_mermaid_docs
node_mermaid_docs -->|"uses generated ERDs"| node_erd_builder
node_cli -->|"adds Mermaid library"| node_html_integration
node_mermaid_docs -->|"updates manifest"| node_generated_docs
node_html_integration -->|"updates HTML"| node_generated_docs
node_user -->|"serves docs"| node_docs_server
node_docs_server -->|"serves existing files"| node_generated_docs

click node_cli "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/cli.py"
click node_validation "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/input_validators.py"
click node_domain "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/domain.py"
click node_erd_builder "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/mermaid.py"
click node_mermaid_docs "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/mermaid.py"
click node_html_integration "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/mermaid.py"
click node_docs_server "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/cli.py"
click node_mermaid_output "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/mermaid.py"
click node_output_writers "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/output_writers.py"
click node_svg_renderer "https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/output_writers.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_dbt_docs,node_artifacts,node_user toneBlue
class node_validation,node_domain,node_erd_builder toneAmber
class node_mermaid_docs,node_html_integration,node_generated_docs,node_docs_server toneMint
class node_mermaid_output,node_output_writers,node_svg_renderer,node_output_files toneRose
```

## Components

### CLI workflow

- [CLI commands](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/cli.py): `dbt_diagrams/cli.py`
- **dbt docs command**
- **dbt artifacts**

### ERD generation

- [Artifact validation](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/input_validators.py): `dbt_diagrams/input_validators.py`
- [ERD domain models](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/domain.py): `dbt_diagrams/domain.py`
- [ERD construction](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/mermaid.py): `dbt_diagrams/mermaid.py`

### dbt docs integration

- [Docs Mermaid insertion](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/mermaid.py): `dbt_diagrams/mermaid.py`
- [Mermaid HTML integration](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/mermaid.py): `dbt_diagrams/mermaid.py`
- **Generated dbt docs**
- [Docs server](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/cli.py): `dbt_diagrams/cli.py`

### Output rendering

- [Mermaid diagram text](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/mermaid.py): `dbt_diagrams/mermaid.py`
- [File output writers](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/output_writers.py): `dbt_diagrams/output_writers.py`
- [SVG browser rendering](https://github.com/djlemkes/dbt-diagrams/blob/main/dbt_diagrams/output_writers.py): `dbt_diagrams/output_writers.py`
- **Exported diagram files**

### Other components

- **dbt project user**

## Connections

- dbt project user → CLI commands: runs (evidence: `README.md`)
- dbt docs command → dbt artifacts: generates (evidence: `README.md`)
- dbt project user → dbt artifacts: provides (evidence: `README.md`)
- CLI commands → dbt docs command: invokes (evidence: `dbt_diagrams/cli.py`)
- CLI commands → Artifact validation: validates (evidence: `dbt_diagrams/cli.py`)
- CLI commands → ERD construction: requests ERDs (evidence: `dbt_diagrams/cli.py`)
- ERD construction → Artifact validation: reads artifacts (evidence: `dbt_diagrams/mermaid.py`)
- ERD construction → ERD domain models: builds models (evidence: `dbt_diagrams/mermaid.py`)
- ERD construction → Mermaid diagram text: generates (evidence: `dbt_diagrams/mermaid.py`)
- CLI commands → File output writers: selects format (evidence: `dbt_diagrams/cli.py`)
- File output writers → SVG browser rendering: renders SVG (evidence: `dbt_diagrams/output_writers.py`)
- File output writers → Exported diagram files: writes (evidence: `dbt_diagrams/output_writers.py`)
- CLI commands → Docs Mermaid insertion: embeds ERDs (evidence: `dbt_diagrams/cli.py`)
- Docs Mermaid insertion → ERD construction: uses generated ERDs (evidence: `dbt_diagrams/cli.py`)
- CLI commands → Mermaid HTML integration: adds Mermaid library (evidence: `dbt_diagrams/cli.py`)
- Docs Mermaid insertion → Generated dbt docs: updates manifest
- Mermaid HTML integration → Generated dbt docs: updates HTML (evidence: `dbt_diagrams/mermaid.py`)
- dbt project user → Docs server: serves docs (evidence: `README.md`)
- Docs server → Generated dbt docs: serves existing files (evidence: `dbt_diagrams/cli.py`)
