# picnicsupermarket/dbt-score architecture

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

- Interactive diagram: https://gitdiagram.com/picnicsupermarket/dbt-score
- Repository: https://github.com/picnicsupermarket/dbt-score

## Overview

##### Project type and purpose
- This is a Python-based, open-source command-line tool (“dbt-score”) whose purpose is to lint and score dbt (Data Build Tool) metadata. It reads a dbt manifest JSON, applies a set of user-configurable rules, computes scores, and outputs results in various formats.

##### File structure
- Top-level directories:
- src/dbt_score: the main package
- docs: documentation (MkDocs)
- tests: pytest test suite
- .github/workflows: CI/CD pipelines
- Key modules under src/dbt_score:
- __main__.py & cli.py — CLI entrypoint (likely built with click/argparse)
- config.py — loading and validating user configuration
- dbt_utils.py — helpers to parse the dbt manifest
- rule_registry.py, rule_catalog.py, rule_filter.py — extensible rule discovery & filtering
- evaluation.py & scoring.py — core logic to apply rules and compute scores
- formatters/… — pluggable output formatters (JSON, human-readable, manifest-annotated, ASCII)
- exceptions.py — custom error types
- Build & packaging: pyproject.toml, pdm.lock, .pre-commit, .prettierrc
- CI workflows define lint, test, release steps.

##### Insights from README
- Describes dbt-score as a “linter for dbt metadata”
- Documents programmatic invocation, CLI flags, configuration model, rule definition syntax, and output formats.
- No external services—operates entirely on local files (dbt manifest).

a. Main components
- CLI Layer
- Configuration Loader
- Manifest Parser (dbt_utils)
- Rule Registry & Catalog
- Rule Filter
- Evaluation Engine
- Scoring Engine
- Formatter Plugins
- Output Sink (stdout, file)
- Tests & CI (side component)
b. Relationships & data flow
- User invokes CLI →
- CLI parses arguments →
- Config Loader reads config file (+ CLI overrides) →
- Manifest Parser loads and normalizes dbt manifest JSON →
- Rule Registry dynamically discovers available rules →
- Rule Filter selects active rules based on config →
- Evaluation Engine applies each rule to manifest models →
- Scoring Engine aggregates rule results into a score →
- Formatter Plugin transforms results into chosen format →
- CLI writes to stdout or files
c. Architectural patterns / principles
- Modular separation of concerns (parsing, rules, evaluation, formatting)
- Plugin-style extensibility for rules and formatters
- Single responsibility per module
- Clear error handling via custom exceptions
d. Key technologies
- Python 3.x (packaged with PDM)
- pytest for testing
- MkDocs for documentation
- CI via GitHub Actions
- CLI framework (e.g., click or built-in argparse)

##### Detail
- Under “Formatter,” show individual formatter plugins (JSON, human-readable, ASCII, manifest).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        Main["__main__.py"]:::input
        CLIcmd["cli.py"]:::input
        Lint["lint.py"]:::input
    end

    %% Configuration & Parsing
    subgraph "Configuration & Parsing"
        Config["config.py"]:::input
        Parser["dbt_utils.py"]:::input
    end

    %% Supporting Modules
    subgraph "Supporting Modules"
        RuleFiltDef["filters.py"]:::processing
        RuleGenDef["generic.py"]:::processing
        Exceptions["exceptions.py"]:::processing
        Models["models.py\nmore_itertools.py\nrule.py"]:::processing
    end

    %% Core Processing
    subgraph "Core Processing"
        Registry["rule_registry.py"]:::processing
        Catalog["rule_catalog.py"]:::processing
        Filter["rule_filter.py"]:::processing
        Eval["evaluation.py"]:::processing
        Scorer["scoring.py"]:::processing
    end

    %% Formatter Plugins
    subgraph "Formatter Plugins"
        ASCII["ascii_formatter.py"]:::output
        HR["human_readable_formatter.py"]:::output
        JSONf["json_formatter.py"]:::output
        ManifestF["manifest_formatter.py"]:::output
    end

    %% Output Sink
    Output["Output Sink\n(stdout/files)"]:::output

    %% Infrastructure
    subgraph "Infrastructure"
        Tests["tests/"]:::infra
        Docs["docs/"]:::infra
        CI[".github/workflows"]:::infra
    end

    %% Data Flow
    Main -->|"invokes"| CLIcmd
    Main -->|"invokes"| Lint
    CLIcmd -->|"args"| Config
    CLIcmd -->|"args"| Parser
    Config -->|"Config object"| Registry
    Parser -->|"Manifest models"| Registry
    Registry -->|"Discovered rules"| Catalog
    Catalog -->|"All rules"| Filter
    Config -->|"Active rules"| Filter
    Filter -->|"Filtered rules"| Eval
    Eval -->|"EvaluationResults"| Scorer
    Scorer -->|"Score summary"| ASCII
    Scorer -->|"Score summary"| HR
    Scorer -->|"Score summary"| JSONf
    Scorer -->|"Score summary"| ManifestF
    ASCII -->|"formatted output"| Output
    HR -->|"formatted output"| Output
    JSONf -->|"formatted output"| Output
    ManifestF -->|"formatted output"| Output

    %% Click Events
    click Main "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/__main__.py"
    click CLIcmd "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/cli.py"
    click Lint "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/lint.py"
    click Config "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/config.py"
    click Parser "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/dbt_utils.py"
    click Registry "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/rule_registry.py"
    click Catalog "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/rule_catalog.py"
    click Filter "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/rule_filter.py"
    click Eval "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/evaluation.py"
    click Scorer "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/scoring.py"
    click ASCII "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/formatters/ascii_formatter.py"
    click HR "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/formatters/human_readable_formatter.py"
    click JSONf "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/formatters/json_formatter.py"
    click ManifestF "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/formatters/manifest_formatter.py"
    click RuleFiltDef "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/rules/filters.py"
    click RuleGenDef "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/rules/generic.py"
    click Exceptions "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/exceptions.py"
    click Models "https://github.com/picnicsupermarket/dbt-score/blob/master/src/dbt_score/models.py"
    click Tests "https://github.com/picnicsupermarket/dbt-score/tree/master/tests/"
    click Docs "https://github.com/picnicsupermarket/dbt-score/tree/master/docs/"
    click CI "https://github.com/picnicsupermarket/dbt-score/tree/master/.github/workflows"

    %% Styles
    classDef input fill:#D0E6FA,stroke:#0288D1,color:#000
    classDef processing fill:#DFF8E1,stroke:#2E7D32,color:#000
    classDef output fill:#FFE0B2,stroke:#EF6C00,color:#000
    classDef infra fill:#E0E0E0,stroke:#9E9E9E,color:#000
```
