How datnguye/dbterd works
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