# antonbabenko/pre-commit-terraform architecture

> Architecture diagram of the GitHub repository antonbabenko/pre-commit-terraform, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/antonbabenko/pre-commit-terraform
- Repository: https://github.com/antonbabenko/pre-commit-terraform

## Overview

##### Project type and purpose
- This is an open-source CLI tool and Docker image providing a collection of Terraform/Terragrunt Git hooks.
- It plugs into the pre-commit framework, orchestrates checks (formatting, validation, security, docs, cost) via Python code and shell scripts, and can be consumed locally, in CI, or as a Docker container.

##### File structure
- Top-level:
- src/pre_commit_terraform/ : Python package (CLI entrypoint, subcommands, parsing, error handling, structs).
- hooks/ : Bash wrapper scripts for each hook (terraform_fmt, terraform_validate, etc.).
- .pre-commit-hooks.yaml & .pre-commit-config.yaml (in readme) define hook IDs, entrypoints, args.
- Dockerfile & tools/entrypoint.sh : build and run container, set up user‐mapping.
- tests/ : unit tests for Python code and performance tests for hooks.
- .github/workflows/* : CI/CD pipelines for building, testing, releasing the image and Python package.
- pyproject.toml, hatch.toml, tox.ini, pytest.ini, and various linters’ configs: packaging, build, and static checks.

##### README for additional insights
- Describes each hook’s purpose (terraform_fmt, terraform_docs, terraform_tflint, terraform_trivy, infracost_breakdown, etc.).
- Shows install options (local via pip, Docker), execution flows, environment variable overrides, and CI/CD examples on GitHub Actions.

##### Detail without over-complicating
- Break the system into the maximum meaningful components listed above.
- Every essential interaction (Git → pre-commit → CLI → hooks → tools).

[Developer Workstation]
│
▼
[pre-commit framework]──reads──>[.pre-commit-hooks.yaml]
│
▼
[pre_commit_terraform Python CLI]──invokes──>[hook script: terraform_fmt.sh]
│                                         ▲
▼                                         │
… other hooks …                              │
│                                         │
▼                                         │
[External Tool: terraform binary]              └─ common.sh library
│
▼
Results → back to CLI → back to pre-commit → Git commit allowed/blocked

Plus side panels for:

- Docker Image (Dockerfile, entrypoint)
- CI/CD (GitHub Actions)
- External APIs (Infracost)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Developer Workstation"
        DevGit["Git Client"]:::external
        PreCommit["pre-commit framework"]:::config
    end

    DevGit -->|commit| PreCommit
    PreCommit -->|loads metadata| ConfigHookYaml[".pre-commit-hooks.yaml"]:::config
    PreCommit -->|invokes| PythonCLI["Python CLI: pre_commit_terraform"]:::python
    click PythonCLI "https://github.com/antonbabenko/pre-commit-terraform/tree/master/src/pre_commit_terraform/"

    subgraph "Python CLI"
        CLI_Main["__main__.py"]:::python
        CLI_Parsing["_cli_parsing.py"]:::python
        CLI_Subcmd["_cli_subcommands.py"]:::python
        CLI_Errors["_errors.py"]:::python
        CLI_Structs["_structs.py"]:::python
        CLI_Types["_types.py"]:::python
        CLI_Docs["terraform_docs_replace.py"]:::python
    end
    click CLI_Main "https://github.com/antonbabenko/pre-commit-terraform/blob/master/src/pre_commit_terraform/__main__.py"
    click CLI_Parsing "https://github.com/antonbabenko/pre-commit-terraform/blob/master/src/pre_commit_terraform/_cli_parsing.py"
    click CLI_Subcmd "https://github.com/antonbabenko/pre-commit-terraform/blob/master/src/pre_commit_terraform/_cli_subcommands.py"
    click CLI_Errors "https://github.com/antonbabenko/pre-commit-terraform/blob/master/src/pre_commit_terraform/_errors.py"
    click CLI_Structs "https://github.com/antonbabenko/pre-commit-terraform/blob/master/src/pre_commit_terraform/_structs.py"
    click CLI_Types "https://github.com/antonbabenko/pre-commit-terraform/blob/master/src/pre_commit_terraform/_types.py"
    click CLI_Docs "https://github.com/antonbabenko/pre-commit-terraform/blob/master/src/pre_commit_terraform/terraform_docs_replace.py"

    PythonCLI -->|dispatches| HookScripts["Hook Shell Scripts"]:::shell
    click HookScripts "https://github.com/antonbabenko/pre-commit-terraform/tree/master/hooks/"

    subgraph "Hook Shell Scripts"
        CommonSH["_common.sh"]:::shell
        FmtSH["terraform_fmt.sh"]:::shell
        ValidateSH["terraform_validate.sh"]:::shell
        DocsSH["terraform_docs.sh"]:::shell
        TFLINTSH["terraform_tflint.sh"]:::shell
        TFSEC_SH["terraform_tfsec.sh"]:::shell
        TRIVYSH["terraform_trivy.sh"]:::shell
        CHECKOVSH["terraform_checkov.sh"]:::shell
        PROVLOCK["terraform_providers_lock.sh"]:::shell
        WRAPPER["terraform_wrapper_module_for_each.sh"]:::shell
        TerragruntFmt["terragrunt_fmt.sh"]:::shell
        TerragruntProv["terragrunt_providers_lock.sh"]:::shell
        TerragruntVal["terragrunt_validate.sh"]:::shell
        TerragruntInp["terragrunt_validate_inputs.sh"]:::shell
        TerrascanSH["terrascan.sh"]:::shell
        TFUPDATE["tfupdate.sh"]:::shell
        InfracostSH["infracost_breakdown.sh"]:::shell
    end
    click CommonSH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/_common.sh"
    click FmtSH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terraform_fmt.sh"
    click ValidateSH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terraform_validate.sh"
    click DocsSH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terraform_docs.sh"
    click TFLINTSH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terraform_tflint.sh"
    click TFSEC_SH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terraform_tfsec.sh"
    click TRIVYSH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terraform_trivy.sh"
    click CHECKOVSH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terraform_checkov.sh"
    click PROVLOCK "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terraform_providers_lock.sh"
    click WRAPPER "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terraform_wrapper_module_for_each.sh"
    click TerragruntFmt "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terragrunt_fmt.sh"
    click TerragruntProv "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terragrunt_providers_lock.sh"
    click TerragruntVal "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terragrunt_validate.sh"
    click TerragruntInp "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terragrunt_validate_inputs.sh"
    click TerrascanSH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/terrascan.sh"
    click TFUPDATE "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/tfupdate.sh"
    click InfracostSH "https://github.com/antonbabenko/pre-commit-terraform/blob/master/hooks/infracost_breakdown.sh"

    subgraph "External Binaries & Services"
        TerraformBin["terraform cli"]:::external
        TFLINTBin["tflint"]:::external
        TFSECBin["tfsec"]:::external
        TrivyBin["trivy"]:::external
        CheckovBin["checkov"]:::external
        TerrascanBin["terrascan"]:::external
        TFUpdateBin["tfupdate"]:::external
        HCLEditBin["hcledit"]:::external
        InfracostAPI["Infracost API"]:::external
        GitHubAPI["GitHub API"]:::external
        ContainerReg["Container Registry"]:::external
    end

    HookScripts -->|exec| TerraformBin
    HookScripts -->|exec| TFLINTBin
    HookScripts -->|exec| TFSECBin
    HookScripts -->|exec| TrivyBin
    HookScripts -->|exec| CheckovBin
    HookScripts -->|exec| TerrascanBin
    HookScripts -->|exec| TFUpdateBin
    HookScripts -->|exec| HCLEditBin
    HookScripts -->|HTTP| InfracostAPI

    TerraformBin -->|exit code| PythonCLI
    TFLINTBin --> PythonCLI
    TFSECBin --> PythonCLI
    TrivyBin --> PythonCLI
    CheckovBin --> PythonCLI
    TerrascanBin --> PythonCLI
    TFUpdateBin --> PythonCLI
    HCLEditBin --> PythonCLI
    InfracostAPI --> PythonCLI

    PythonCLI -->|results| PreCommit
    PreCommit -->|allow/block| DevGit

    subgraph "Docker Image"
        DockerfileFile["Dockerfile"]:::docker
        Entrypoint["tools/entrypoint.sh"]:::docker
        InstallScripts["tools/install/"]:::docker
    end
    click DockerfileFile "https://github.com/antonbabenko/pre-commit-terraform/tree/master/Dockerfile"
    click Entrypoint "https://github.com/antonbabenko/pre-commit-terraform/blob/master/tools/entrypoint.sh"
    click InstallScripts "https://github.com/antonbabenko/pre-commit-terraform/tree/master/tools/install/"

    DockerfileFile --> Entrypoint
    Entrypoint -->|bind-mount & run| PreCommit
    Entrypoint --> PythonCLI

    subgraph "CI/CD (GitHub Actions)"
        Workflows[".github/workflows/"]:::ci
    end
    click Workflows "https://github.com/antonbabenko/pre-commit-terraform/tree/master/.github/workflows/"

    Workflows -->|build image| DockerfileFile
    Workflows -->|publish package & image| ContainerReg
    Workflows -->|run tests| TestsGroup

    subgraph "Config & Metadata"
        ConfigPreCommit[".pre-commit-config.yaml"]:::config
        Pyproject["pyproject.toml"]:::config
        Hatch["hatch.toml"]:::config
        Tox["tox.ini"]:::config
        PytestIni["pytest.ini"]:::config
        Ruff["ruff.toml"]:::config
        Flake[".flake8"]:::config
        Mypy[".mypy.ini"]:::config
        EditorConfig[".editorconfig"]:::config
    end

    PreCommit --> ConfigPreCommit

    subgraph "Tests"
        CliTest["_cli_test.py"]:::test
        DocsTest["terraform_docs_replace_test.py"]:::test
        PerfTest["hooks_performance_test.sh"]:::test
        DockerTest["Dockerfile"]:::test
    end
    click CliTest "https://github.com/antonbabenko/pre-commit-terraform/blob/master/tests/pytest/_cli_test.py"
    click DocsTest "https://github.com/antonbabenko/pre-commit-terraform/blob/master/tests/pytest/terraform_docs_replace_test.py"
    click PerfTest "https://github.com/antonbabenko/pre-commit-terraform/blob/master/tests/hooks_performance_test.sh"
    click DockerTest "https://github.com/antonbabenko/pre-commit-terraform/tree/master/tests/Dockerfile"

    classDef python fill:#bbdefb,stroke:#1e88e5;
    classDef shell fill:#c8e6c9,stroke:#2e7d32;
    classDef external fill:#eceff1,stroke:#607d8b,stroke-dasharray: 5 5;
    classDef config fill:#fff3e0,stroke:#ef6c00,stroke-dasharray: 2 2;
    classDef docker fill:#ffe0b2,stroke:#fb8c00;
    classDef ci fill:#e1bee7,stroke:#8e24aa;
    classDef test fill:#fff9c4,stroke:#fbc02d;
```
