# gauge-sh/tach architecture

> Architecture diagram of the GitHub repository gauge-sh/tach, 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/gauge-sh/tach
- Repository: https://github.com/gauge-sh/tach

## Overview

##### Main Components
- CLI Interface – a command layer exposed via commands like “tach init”, “tach check”, “tach show”, and “tach report”. This is visible in both the Python (python/tach/cli.py, __main__.py) and Rust (src/cli.rs) parts.
- Configuration & Setup – configuration files like tach.toml and tach.domain.toml (in various parts of the project), along with modules under src/config and python/tach/parsing/config.py. These control declared dependencies, module boundaries, source roots, public interfaces, and layers.
- Dependency Enforcement Engine – the heart of the project that parses Python code, builds dependency maps, and enforces the “no cycles”, “declared dependencies only”, and “public interface” rules. Note the directories for dependency mapping (src/dep_map in Rust and python/tach/dependencies in Python), processors (src/processors/*), and the error/diagnostics subsystems (src/diagnostics, python/tach/errors, and python/tach/logging).
- Filesystem & Project Discovery – modules handling file system operations, Git interactions, and project layout discovery (e.g., python/tach/filesystem; src/filesystem.rs).
- Reporting & Visualization – components that generate output for the user: the “tach show” command that produces a dependency graph (DOT file or web visualization), and “tach report” for detailed dependency/usage info. These functions are supported by modules like src/commands/report.rs and python/tach/report.py.
- CI/CD & Integration – the GitHub workflows and Makefile indicate that Tach is integrated into automated testing and deployment pipelines. Also, support for pre-commit hooks (see python/tach/hooks and documentation on installing hooks) provides integration points for continuous enforcement.

##### Relationships and Interactions
- CLI commands (from both Python and Rust entry points) serve as the starting point. They trigger the configuration loader, which reads tach.toml and possibly tach.domain.toml files.
- Once configuration is loaded, the enforcement engine kicks in: it uses the parsing modules (both in Rust and Python) to inspect the project’s dependency structure, consults the configuration regarding allowed dependencies, and then uses filesystem operations to traverse the module files.
- If violations occur, the diagnostics and logging components record and report errors (with error messages including file paths and line numbers).
- In parallel, during commands like “tach show” the dependency engine outputs the graph data – either by creating a DOT file for local GraphViz processing or by sending data to a remote visualization engine (as described in the README).

##### Architectural Patterns and Design Principles
- The project embraces a layered (or modular) monolith architecture where clear boundaries between modules are enforced.
- Separation of concerns is evident: configuration, parsing, dependency analysis, and reporting/logging are all isolated.
- There is a clear division between the CLI/presentation layer (both in Python and Rust) and the domain logic (dependency enforcement, diagnostics, and graph generation).
- The design supports incremental adoption: not every module needs immediate full conformance and there are options to deprecate or ignore certain dependencies.

##### Technologies, Frameworks, and Libraries
- Rust is used to build the core of the tool (with files under src/). Look for the usage of Cargo and Rust modules.
- Python is used for the CLI integration and tooling (under python/tach), suggesting use of standard libraries and possibly popular Python CLI libraries.
- GraphViz integration is mentioned for DOT file generation.
- CI/CD configuration via GitHub Actions and pre-commit hooks is set up, indicating a commitment to continuous integration.

- Annotations or labels that reference key principles like “Modular Monolith”, “Enforced Dependencies”, “Public Interfaces”, and “Cycle Prevention”.
- Be as granular as possible by separating modules into their architectural layers (e.g., configuration, processing, reporting) to clearly communicate the design’s complexity and extensibility.

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% CLI Interfaces
    subgraph "CLI Interfaces"
        rustCLI("Rust CLI Interface"):::rust
        pyCLI1("Python CLI (cli.py)"):::python
        pyCLI2("Python CLI (__main__.py)"):::python
    end

    %% Configuration & Setup
    subgraph "Configuration & Setup"
        confFile("Configuration File"):::config
        confDomain("Domain Config File"):::config
        rustConfig("Rust Config Modules"):::rust
        pyConfig("Python Config Parser"):::python
    end

    %% Intermediate: Loaded Configuration
    loadedConf("Loaded Configuration"):::config

    %% Dependency Enforcement Engine
    subgraph "Dependency Enforcement Engine"
        subgraph "Rust Engine"
            rustDep("Rust Dependency Mapping"):::rust
            rustProc("Rust Processors"):::rust
            rustDiag("Rust Diagnostics"):::rust
        end
        subgraph "Python Engine"
            pyErr("Python Errors"):::python
            pyLog("Python Logging"):::python
        end
    end

    %% Filesystem & Project Discovery
    subgraph "Filesystem & Project Discovery"
        rustFS("Rust Filesystem Module"):::rust
        pyFS("Python Filesystem Operations"):::python
    end

    %% Reporting & Visualization
    subgraph "Reporting & Visualization"
        rustRep("Rust Reporting Command"):::rust
        pyRep("Python Report"):::python
        pyShow("Python Show"):::python
    end

    %% CI/CD & Integration
    subgraph "CI/CD & Integration"
        gw("GitHub Workflows"):::ci
        pre("Pre-commit Hooks"):::ci
    end

    %% Connections: CLI -> Configuration & Setup
    rustCLI -->|"triggers"| confFile
    rustCLI -->|"triggers"| rustConfig
    pyCLI1 -->|"triggers"| confDomain
    pyCLI1 -->|"triggers"| pyConfig
    pyCLI2 -->|"triggers"| confDomain
    pyCLI2 -->|"triggers"| pyConfig

    %% Merge Configuration into Loaded Configuration
    confFile --> loadedConf
    confDomain --> loadedConf
    rustConfig --> loadedConf
    pyConfig --> loadedConf

    %% Loaded Configuration flows to Dependency Enforcement Engine
    loadedConf --> rustDep
    loadedConf --> pyErr

    %% Dependency Engine uses Filesystem operations
    rustProc --> rustFS
    pyLog --> pyFS

    %% Dependency Engine outputs to Reporting & Visualization
    rustDiag --> rustRep
    pyLog --> pyRep
    pyLog --> pyShow

    %% Error reporting back to CLI Interfaces
    rustDiag -->|"reports error"| rustCLI
    pyErr -->|"reports error"| pyCLI1
    pyErr -->|"reports error"| pyCLI2

    %% CI/CD integration feeds into Python CLI for automation
    pre -->|"hooks"| pyCLI1
    gw -->|"triggers"| pyCLI1

    %% Styling Classes
    classDef rust fill:#F08080,stroke:#333,stroke-width:2px;
    classDef python fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef config fill:#C8E6C9,stroke:#333,stroke-width:2px;
    classDef ci fill:#FFECB3,stroke:#333,stroke-width:2px;

    %% Click Events for CLI Interfaces
    click rustCLI "https://github.com/gauge-sh/tach/blob/main/src/cli.rs"
    click pyCLI1 "https://github.com/gauge-sh/tach/blob/main/python/tach/cli.py"
    click pyCLI2 "https://github.com/gauge-sh/tach/blob/main/python/tach/__main__.py"

    %% Click Events for Configuration & Setup
    click confFile "https://github.com/gauge-sh/tach/blob/main/tach.toml"
    click confDomain "https://github.com/gauge-sh/tach/blob/main/python/tach/filesystem/tach.domain.toml"
    click rustConfig "https://github.com/gauge-sh/tach/tree/main/src/config/"
    click pyConfig "https://github.com/gauge-sh/tach/blob/main/python/tach/parsing/config.py"

    %% Click Events for Dependency Enforcement Engine
    click rustDep "https://github.com/gauge-sh/tach/tree/main/src/dep_map/"
    click rustProc "https://github.com/gauge-sh/tach/tree/main/src/processors/"
    click rustDiag "https://github.com/gauge-sh/tach/tree/main/src/diagnostics/"
    click pyErr "https://github.com/gauge-sh/tach/tree/main/python/tach/errors/"
    click pyLog "https://github.com/gauge-sh/tach/blob/main/python/tach/logging/logger.py"

    %% Click Events for Filesystem & Project Discovery
    click rustFS "https://github.com/gauge-sh/tach/blob/main/src/filesystem.rs"
    click pyFS "https://github.com/gauge-sh/tach/tree/main/python/tach/filesystem/"

    %% Click Events for Reporting & Visualization
    click rustRep "https://github.com/gauge-sh/tach/blob/main/src/commands/report.rs"
    click pyRep "https://github.com/gauge-sh/tach/blob/main/python/tach/report.py"
    click pyShow "https://github.com/gauge-sh/tach/blob/main/python/tach/show.py"

    %% Click Events for CI/CD & Integration
    click gw "https://github.com/gauge-sh/tach/tree/main/.github/workflows/"
    click pre "https://github.com/gauge-sh/tach/tree/main/python/tach/hooks/"
```
