# datnguye/dbterd architecture

> Architecture diagram of the GitHub repository datnguye/dbterd, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/datnguye/dbterd
- Repository: https://github.com/datnguye/dbterd

## Overview

##### Project type and purpose
- **Type**: A Python-based CLI tool & library.

##### File structure
- **Entry points**
- `dbterd/__main__.py`, `dbterd/main.py` – CLI bootstrap
- `dbterd/cli/` – CLI argument definitions & runner
- **Core API**
- `dbterd/api/DbtErd` – high-level Python API
- `dbterd/default.py`, `dbterd/types.py`, `dbterd/constants.py` – core definitions
- **Adapters** (strategy pattern)
- **Source adapters**:
– `dbt_core/dbt_invocation.py` (local artifact parsing)
– `dbt_cloud/(graphql, discovery, administrative)` (remote metadata fetch)
- **Algorithm adapters** (`adapters/algos`):
– `semantic.py`, `test_relationship.py` – two relationship-detection strategies
- **Target adapters** (`adapters/targets`):
- **Helpers & Utilities**
- `dbterd/helpers/*` – file I/O, JSON/YAML, logging, CLI messaging
- **Configuration & docs**
- `pyproject.toml`, `.github/workflows/` for CI/publishing
- `docs/`, `mkdocs.yml` – project documentation site
- **Tests**
- `tests/unit/` – isolated tests for CLI, adapters, helpers

##### README for additional insights
- **Workflow**:
1. `dbterd run …` (CLI)
2. Select and parse artifacts (local files or Cloud GraphQL)
3. Build an ER model using chosen algorithm
4. Emit ERD code via the chosen target adapter
- **Tech stack**: Python 3.9–3.12, optional dependency on `dbt-artifacts-parser`, GraphQL client

a. **Main components**
- CLI Layer (Entrypoint): `dbterd/cli` + `__main__`
- Core Engine: `DbtErd` API + default/core modules
- Source Adapters: `dbt_core`, `dbt_cloud`
- Algorithm Layer: `test_relationship`, `semantic`
- Helpers & Utilities
- External Inputs/Outputs:
- On-disk artifact files (`manifest.json`, `catalog.json`)
- dbt Cloud GraphQL endpoint
- Generated ERD-code files (stdout, files)
b. **Relationships & data flows**
- CLI → Core Engine (passes CLI params)
- Core Engine → Source Adapter (fetch/parse artifacts)
- Source Adapter → Core Engine (returns parsed model metadata)
- Core Engine → Algorithm Adapter (build ER model)
- Algorithm Adapter → Core Engine (returns ER graph structure)
- Core Engine → Target Adapter (generate ERD code)
- Target Adapter → Output sink (stdout/file)
c. **Architectural patterns**
- Strategy Pattern: interchangeable Algorithm and Target adapters
- Adapter Pattern: uniform interface for multiple source-parsing backends
- Layered Architecture: CLI → Core → Plugins (adapters) → I/O
d. **Key technologies/frameworks**
- Python standard library + `click` or internal CLI parsing
- GraphQL for dbt Cloud
- `dbt-artifacts-parser` (optional)
- MkDocs for docs site
- CI workflows for testing & publishing

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Inputs
    Artifacts["Local Artifacts\n(manifest.json, catalog.json)"]:::external
    GraphQLEndpoint["dbt Cloud GraphQL\nEndpoint"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        CLI_Main["dbterd/__main__.py"]:::core
        CLI_Main2["dbterd/main.py"]:::core
        CLI_Pkg["dbterd/cli/"]:::core
    end

    %% Core Engine
    subgraph "Core Engine"
        DbtErd["DbtErd API\n(dbterd/api/)"]:::core
        Defaults["default.py, constants.py,\ntypes.py"]:::core
    end

    %% Adapter Infrastructure
    subgraph "Adapter Infrastructure"
        Adapter_CoreAdapter["dbterd/adapters/adapter.py"]:::infra
        Adapter_Base["dbterd/adapters/base.py"]:::infra
        FilterHelpers["dbterd/adapters/filter.py"]:::infra
        MetaHelpers["dbterd/adapters/meta.py"]:::infra
    end

    %% Source Adapters
    subgraph "Source Adapters"
        DbtCore["dbt_core/dbt_invocation.py"]:::source
        DbtCloud_GQL["dbt_cloud/graphql.py"]:::source
        DbtCloud_Discovery["dbt_cloud/discovery.py"]:::source
        DbtCloud_Admin["dbt_cloud/administrative.py"]:::source
        DbtCloud_Query["dbt_cloud/query.py"]:::source
        DbtCloud_Includes["dbt_cloud/include/*.gql"]:::source
    end

    %% Algorithm Adapters
    subgraph "Algorithm Adapters"
        Algo_Base["base.py"]:::algo
        Algo_Semantic["semantic.py"]:::algo
        Algo_Test["test_relationship.py"]:::algo
    end

    %% Target Adapters
    subgraph "Target Adapters"
        Target_DBML["dbml.py"]:::target
        Target_Mermaid["mermaid.py"]:::target
        Target_PlantUML["plantuml.py"]:::target
        Target_GraphViz["graphviz.py"]:::target
        Target_D2["d2.py"]:::target
        Target_DrawDB["drawdb.py"]:::target
    end

    %% Helpers & Utilities
    Helpers["dbterd/helpers/"]:::helpers

    %% Outputs
    ERDOut["Generated ERD Code\n(DBML, Mermaid, PlantUML, GraphViz, D2, DrawDB)"]:::output

    %% Data Flows
    Artifacts -->|reads| DbtCore
    GraphQLEndpoint -->|fetches| DbtCloud_GQL
    DbtCore -->|parses| DbtErd
    DbtCloud_GQL -->|parses| DbtErd
    DbtCloud_Discovery -->|metadata| DbtErd
    DbtCloud_Admin -->|metadata| DbtErd
    DbtCloud_Query -->|queries| DbtErd
    DbtCloud_Includes -->|uses| DbtCloud_GQL

    CLI_Main -->|invokes| DbtErd
    CLI_Main2 -->|invokes| DbtErd
    CLI_Pkg -->|passes params| DbtErd

    DbtErd -->|uses| Adapter_CoreAdapter
    DbtErd -->|uses| Adapter_Base
    DbtErd -->|uses| FilterHelpers
    DbtErd -->|uses| MetaHelpers

    DbtErd -->|builds ER| Algo_Base
    DbtErd -->|strategy| Algo_Semantic
    DbtErd -->|strategy| Algo_Test

    DbtErd -->|renders| Target_DBML
    DbtErd -->|renders| Target_Mermaid
    DbtErd -->|renders| Target_PlantUML
    DbtErd -->|renders| Target_GraphViz
    DbtErd -->|renders| Target_D2
    DbtErd -->|renders| Target_DrawDB

    Helpers -->|supports| DbtErd
    Helpers -->|supports| Adapter_CoreAdapter
    Helpers -->|supports| Adapter_Base
    Helpers -->|supports| FilterHelpers
    Helpers -->|supports| MetaHelpers

    Target_DBML -->|outputs| ERDOut
    Target_Mermaid -->|outputs| ERDOut
    Target_PlantUML -->|outputs| ERDOut
    Target_GraphViz -->|outputs| ERDOut
    Target_D2 -->|outputs| ERDOut
    Target_DrawDB -->|outputs| ERDOut

    %% Click Events
    click CLI_Main "https://github.com/datnguye/dbterd/blob/main/dbterd/__main__.py"
    click CLI_Main2 "https://github.com/datnguye/dbterd/blob/main/dbterd/main.py"
    click CLI_Pkg "https://github.com/datnguye/dbterd/tree/main/dbterd/cli/"
    click DbtErd "https://github.com/datnguye/dbterd/tree/main/dbterd/api/"
    click Defaults "https://github.com/datnguye/dbterd/blob/main/dbterd/default.py"
    click Defaults "https://github.com/datnguye/dbterd/blob/main/dbterd/constants.py"
    click Defaults "https://github.com/datnguye/dbterd/blob/main/dbterd/types.py"
    click Adapter_CoreAdapter "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/adapter.py"
    click Adapter_Base "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/base.py"
    click FilterHelpers "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/filter.py"
    click MetaHelpers "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/meta.py"
    click DbtCore "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/dbt_core/dbt_invocation.py"
    click DbtCloud_GQL "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/dbt_cloud/graphql.py"
    click DbtCloud_Discovery "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/dbt_cloud/discovery.py"
    click DbtCloud_Admin "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/dbt_cloud/administrative.py"
    click DbtCloud_Query "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/dbt_cloud/query.py"
    click DbtCloud_Includes "https://github.com/datnguye/dbterd/tree/main/dbterd/adapters/dbt_cloud/include/"
    click Algo_Base "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/algos/base.py"
    click Algo_Semantic "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/algos/semantic.py"
    click Algo_Test "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/algos/test_relationship.py"
    click Target_DBML "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/targets/dbml.py"
    click Target_Mermaid "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/targets/mermaid.py"
    click Target_PlantUML "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/targets/plantuml.py"
    click Target_GraphViz "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/targets/graphviz.py"
    click Target_D2 "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/targets/d2.py"
    click Target_DrawDB "https://github.com/datnguye/dbterd/blob/main/dbterd/adapters/targets/drawdb.py"
    click Helpers "https://github.com/datnguye/dbterd/tree/main/dbterd/helpers/"

    %% Styles
    classDef core fill:#cce5ff,stroke:#004085,color:#004085
    classDef source fill:#d4edda,stroke:#155724,color:#155724
    classDef algo fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef target fill:#fff3cd,stroke:#856404,color:#856404
    classDef infra fill:#e2e3e5,stroke:#6c757d,color:#6c757d
    classDef helpers fill:#f8f9fa,stroke:#343a40,color:#343a40
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-dasharray: 5 5
    classDef output fill:#fff3cd,stroke:#856404,color:#856404,stroke-dasharray: 2 2
```
