# k1low/tbls architecture

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

- Interactive diagram: https://gitdiagram.com/k1low/tbls
- Repository: https://github.com/k1low/tbls

## Overview

##### Main Components
- CLI Interface / Entry Point:
– Represented by main.go and the cmd/ directory files (e.g., cmd.go, version.go, diff.go, doc.go, etc.).
– This component is responsible for parsing command-line arguments and dispatching the appropriate commands.
- Command Utilities:
– Modules in the cmdutil/ package that provide shared options and helper functions.
- Configuration Management:
– The config/ directory manages .tbls.yml file parsing, validation, and linting rules.
- Database Schema Connectors / Datasources:
– The datasource/ directory handles basic connection logic.
– The drivers/ directory contains multiple subdirectories (bq, clickhouse, dynamodb, mariadb, mssql, mysql, postgres, redshift, etc.) for connecting and handling different database types.
– This layer parses the DSN and executes the schema extraction.
- Schema & Document Processing:
– The schema/ directory encapsulates the extraction, modeling, and transformation of the database schema.
– The ddl/ and dict/ folders indicate additional processing for DDL parsing and dictionary replacements.
- Output Generation:
– Templates for these outputs reside within these folders (often with corresponding template files in the output/<format>/templates).
- Testing & Continuous Integration:
– The testdata/ and testutil/ directories support automated testing and CI.
– The .github folder contains workflows for CI (build, release, integration tests).

##### Relationships and Interactions
- The CLI (main.go and cmd/) accepts user-input (DSN, configuration options) and then dispatches operations by calling into the configuration module.
- The configuration module reads .tbls.yml (also considering environment variables) and configures settings for data connection, output paths, and linting rules.
- Using the DSN, the datasource and drivers layers establish connections to various databases (or read JSON/HTTP inputs) and extract the schema, resulting in an intermediate representation stored in the schema/ module.
- This intermediate schema is then processed by components in the output/ directory to render files using format-specific templates (Markdown, DOT, etc.). The output is generated either directly or after optional lint and diff checks.
- Testing frameworks in testdata/ and testutil/ verify the correct behavior of infrastructure modules like DDL parsing, templating, and command handling.
- All these components work together, garnering support from shared modules (like cmdutil/) and the CI/CD automation defined in .github workflows.

##### Architectural Patterns & Design Principles
- Modular design: Each major domain is separated (commands, config, drivers, output, schema, etc.) to allow lightweight maintenance and extensibility.
- Plugin-like extensibility: The drivers folder supports multiple databases with similar interfaces, facilitating extension for other datasources.
- Single-binary distribution: Consolidation of all functionality into one executable for CI ease-of-use.
- Template-based output generation: Customizability via personalized templates (see the personalized templates section in the README) to tailor the generated documentation.
- Command-line utility pattern: Clear separation of sub-commands (doc, diff, lint, coverage, etc.) to maintain simplicity and usability.

##### Relevant Technologies, Frameworks, and Libraries
- Go programming language for all core implementations.
- GitHub Actions and CI configuration files (e.g., workflows in .github) for continuous integration.
- Docker (Dockerfile and compose.yml) for containerized execution.
- External configuration (YAML via .tbls.yml) and templating for customizable outputs.
- The various Go modules like golangci-lint (via .golangci.yml) and goreleaser for building and releasing.

##### Elements
- Clear labels for each major component (CLI, Configuration, Datasource, Schema Processor, Output Generator, CI/CD Pipeline, etc.).
- Input flow: Command-line parameters and .tbls.yml configuration.
- Data flow: DSN parsing → Data extraction (via various drivers) → Schema conversion → Documentation output.
- Feedback flow: Diff and lint processing, which reports back to the user and can be integrated with CI pipelines.
- Annotations to indicate design patterns (e.g., plugin architecture in drivers, template-based output generation) and frameworks (e.g., GitHub Actions for CI, Docker for containerization).

– Begin at the user interface (CLI & main.go) which reads configuration (.tbls.yml) and environment variables.
– Show the interconnection with the configuration management module.
– Demonstrate how the tool leverages the datasource and drivers layers to extract and model the database schema.
– Illustrate the processing of the schema into various documentation formats via the output generation modules.
– Include supporting layers for linting, diffing, and continuous integration.
– Finally, mark supporting directories (tests, scripts, CI workflows) that provide additional context for development, testing, and deployment.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Input & CLI
    subgraph "User Input & CLI"
        CLI_Main["CLI Interface"]:::cli
        CLI_Cmd["CLI Commands"]:::cli
        Cmd_Utilities["Command Utilities"]:::utility
    end

    %% Configuration Management
    subgraph "Configuration"
        Config_Mgmt["Configuration Management"]:::config
    end

    %% Database Connection
    subgraph "Database Connection"
        Datasource["Datasource Connectors"]:::datasource
        subgraph "Drivers"
            Postgres_Driver["Postgres Driver"]:::driver
            MySQL_Driver["MySQL Driver"]:::driver
        end
    end

    %% Schema & Document Processing
    subgraph "Schema Processing"
        Schema_Proc["Schema Processing"]:::schema
        DDL_Proc["DDL Parsing"]:::schema
        Dict_Proc["Dictionary Replacement"]:::schema
    end

    %% Output Generation
    subgraph "Output Generation"
        Markdown["Markdown Output"]:::output
        DOT["DOT Output"]:::output
        Mermaid["Mermaid Output"]:::output
        PlantUML["PlantUML Output"]:::output
        JSON["JSON Output"]:::output
        XLSX["Excel Output"]:::output
        YAML["YAML Output"]:::output
    end

    %% Testing & Continuous Integration
    subgraph "Testing & CI"
        Testing["Testing Directories"]:::testing
        CI["CI/CD Pipeline"]:::ci
    end

    %% Connections
    CLI_Main --> Config_Mgmt
    CLI_Cmd --> Config_Mgmt
    Cmd_Utilities --> Config_Mgmt

    Config_Mgmt --> Datasource

    Datasource --> Postgres_Driver
    Datasource --> MySQL_Driver

    Postgres_Driver --> Schema_Proc
    MySQL_Driver --> Schema_Proc

    Schema_Proc --> DDL_Proc
    Schema_Proc --> Dict_Proc

    Schema_Proc --> Markdown
    Schema_Proc --> DOT
    Schema_Proc --> Mermaid
    Schema_Proc --> PlantUML
    Schema_Proc --> JSON
    Schema_Proc --> XLSX
    Schema_Proc --> YAML

    %% Testing & CI feedback (dashed arrows)
    Testing -.-> CLI_Main
    CI -.-> Config_Mgmt
    CI -.-> Datasource
    CI -.-> Schema_Proc
    CI -.-> Markdown

    %% Click Events
    click CLI_Main "https://github.com/k1low/tbls/blob/main/main.go"
    click CLI_Cmd "https://github.com/k1low/tbls/blob/main/cmd/cmd.go"
    click Cmd_Utilities "https://github.com/k1low/tbls/blob/main/cmdutil/option.go"
    click Config_Mgmt "https://github.com/k1low/tbls/blob/main/config/config.go"
    click Datasource "https://github.com/k1low/tbls/blob/main/datasource/datasource.go"
    click Postgres_Driver "https://github.com/k1low/tbls/blob/main/drivers/postgres/postgres.go"
    click MySQL_Driver "https://github.com/k1low/tbls/blob/main/drivers/mysql/mysql.go"
    click Schema_Proc "https://github.com/k1low/tbls/blob/main/schema/schema.go"
    click DDL_Proc "https://github.com/k1low/tbls/blob/main/ddl/ddl.go"
    click Dict_Proc "https://github.com/k1low/tbls/blob/main/dict/dict.go"
    click Markdown "https://github.com/k1low/tbls/tree/main/output/md/"
    click DOT "https://github.com/k1low/tbls/tree/main/output/dot/"
    click Mermaid "https://github.com/k1low/tbls/tree/main/output/mermaid/"
    click PlantUML "https://github.com/k1low/tbls/tree/main/output/plantuml/"
    click JSON "https://github.com/k1low/tbls/tree/main/output/json/"
    click XLSX "https://github.com/k1low/tbls/tree/main/output/xlsx/"
    click YAML "https://github.com/k1low/tbls/tree/main/output/yaml/"
    click Testing "https://github.com/k1low/tbls/tree/main/testdata/"
    click CI "https://github.com/k1low/tbls/blob/main/.github/workflows/ci.yml"

    %% Styles
    classDef cli fill:#f9e79f,stroke:#333,stroke-width:2px;
    classDef utility fill:#aed6f1,stroke:#333,stroke-width:2px;
    classDef config fill:#a9dfbf,stroke:#333,stroke-width:2px;
    classDef datasource fill:#fad7a0,stroke:#333,stroke-width:2px;
    classDef driver fill:#f5cba7,stroke:#333,stroke-width:2px;
    classDef schema fill:#d2b4de,stroke:#333,stroke-width:2px;
    classDef output fill:#abebc6,stroke:#333,stroke-width:2px;
    classDef testing fill:#f9c4d2,stroke:#333,stroke-width:2px;
    classDef ci fill:#fdac8b,stroke:#333,stroke-width:2px;
```
