# zupit/horusec architecture

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

- Interactive diagram: https://gitdiagram.com/zupit/horusec
- Repository: https://github.com/zupit/horusec

## Overview

##### Project type and purpose
- This is a Go-based, full-stack CLI tool (Horusec CLI) for static code analysis.
- It orchestrates multiple language analyzers (via Docker or local binaries), collects and formats findings, and can send results to an external Horusec Web API or output to the console/JSON/SARIF.

##### File structure
- Top-level:
- cmd/app – entrypoints for the CLI (generate, start, version)
- config – loading and defaulting of CLI config
- internal – the Go application core split into controllers, entities, enums, helpers, usecases, utils
- internal/services – adapters for Docker, Git, Horusec API, Sarif, SonarQube, and per-language engines and formatters
- deployments – Dockerfiles, release scripts, install scripts
- e2e – CLI end-to-end test suites
- examples, assets – demonstration code and images
- Patterns: layered architecture (presentation in cmd, application in controllers & usecases, domain in entities/enums, infrastructure in services).
- Config files (.golangci.yml, goreleaser.yml) and CI workflows in .github/workflows orchestrate builds, tests, releases.

##### README for additional insights
- Confirms core architecture: CLI → analysis engines → formatters → results → optional Horusec-Web API.
- Provides an “architecture” image showing CLI calling Docker containers for each tool, collecting and unifying results.

##### Details to capture
- Each CLI command (“generate”, “start”, “version”) entrypoint
- Config precedence (example JSON, defaults)
- Requirement checks before analysis
- Parallel execution of language engines
- Aggregation of vulnerabilities across all engines
- Formatting pipeline and optional API submission

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer"
        CLI_Main["Horusec CLI Main"]:::presentation
        Generate["generate Command"]:::presentation
        Start["start Command"]:::presentation
        Version["version Command"]:::presentation
        ConfigLoader["Config Loader"]:::presentation
        DistConfig["Default Config"]:::presentation
    end

    %% Application Layer
    subgraph "Application Layer"
        CLIUsecase["CLI Use Case Entry"]:::application
        AnalyzerOrch["Analysis Orchestrator"]:::application
        Runner["Analyzer Runner"]:::application
        LangDetect["Language Detection"]:::application
        ReqChecker["Requirements Checker"]:::application
        ResultsPrinter["Results Printer"]:::application
    end

    %% Domain Layer
    subgraph "Domain Layer"
        Workdir["Working Directory Model"]:::domain
        AnalysisData["Docker Analysis Data"]:::domain
        ToolsConfig["Tools Configuration"]:::domain
        CustomImages["Custom Images Configuration"]:::domain
        ImagesEnum["Docker/Image Constants"]:::domain
        OutputTypeEnum["Output Type Enum"]:::domain
        ToIgnoreEnum["Ignore-Patterns Enum"]:::domain
    end

    %% Infrastructure Layer
    subgraph "Infrastructure Layer"
        subgraph Services
            DockerClient["Docker Client Config"]:::infra
            DockerAPI["Docker API"]:::infra
            GitService["Git Service"]:::infra
            HorusecAPI["Horusec Web API Client"]:::infra
            SARIFAdapter["SARIF Output Adapter"]:::infra
            SonarQubeAdapter["SonarQube Output Adapter"]:::infra
            CustomRules["Custom Rules Service"]:::infra
            subgraph "Analysis Engines"
                Engines["Language Engines"]:::infra
            end
            subgraph "Formatters"
                Formatters["Formatters"]:::infra
            end
        end
    end

    %% Utilities & Helpers
    subgraph "Utilities & Helpers"
        Messages["Messaging Helpers"]:::util
        FileUtil["File Utility"]:::util
        JSONUtil["JSON Utility"]:::util
        PromptUtil["Prompt Utility"]:::util
        CopyUtil["Copy Utility"]:::util
        DefaultValUtil["Value-or-Default Helper"]:::util
        VulnHash["Vulnerability Hashing"]:::util
        TestUtils["Test Mocks & Helpers"]:::util
    end

    %% External Dependencies
    subgraph "External"
        DockerDaemon(("Docker Daemon")):::external
        GitBinary(("Git Binary")):::external
        HorusecWebAPI(("Horusec Web API")):::external
        JSONOutput[(JSON Output)]:::external
        SARIFFile[(SARIF File)]:::external
    end

    %% Relationships
    CLI_Main -->|invokes| Generate
    CLI_Main -->|invokes| Start
    CLI_Main -->|invokes| Version
    Generate -->|loads| ConfigLoader
    Start -->|loads| ConfigLoader
    Version -->|loads| ConfigLoader
    ConfigLoader -->|provides config| CLIUsecase
    CLIUsecase -->|orchestrates| AnalyzerOrch
    AnalyzerOrch -->|checks| ReqChecker
    ReqChecker -->|uses| DockerDaemon
    ReqChecker -->|uses| GitBinary
    AnalyzerOrch -->|detects languages| LangDetect
    AnalyzerOrch -->|runs| Runner
    Runner -->|spins containers| DockerDaemon
    Runner -->|runs| Engines
    Runner -->|runs| Formatters
    Runner -->|collects data| AnalysisData
    Engines -->|raw results| AnalysisData
    AnalysisData -->|sent to| Formatters
    Formatters -->|unified model| ResultsPrinter
    ResultsPrinter -->|outputs| JSONOutput
    ResultsPrinter -->|outputs| SARIFFile
    ResultsPrinter -->|submits| HorusecAPI
    HorusecAPI -->|calls| HorusecWebAPI
    DockerClient -->|configures| DockerAPI
    DockerAPI -->|communicates| DockerDaemon
    GitService -->|executes| GitBinary
    SARIFAdapter -->|writes| SARIFFile
    SonarQubeAdapter -->|writes| JSONOutput
    CustomRules -->|interfaces| Engines

    %% Click Events
    click CLI_Main "https://github.com/zupit/horusec/blob/main/cmd/app/main.go"
    click Generate "https://github.com/zupit/horusec/blob/main/cmd/app/generate/generate.go"
    click Start "https://github.com/zupit/horusec/blob/main/cmd/app/start/start.go"
    click Version "https://github.com/zupit/horusec/blob/main/cmd/app/version/version.go"
    click ConfigLoader "https://github.com/zupit/horusec/blob/main/config/config.go"
    click DistConfig "https://github.com/zupit/horusec/blob/main/config/dist/dist.go"
    click AnalyzerOrch "https://github.com/zupit/horusec/blob/main/internal/controllers/analyzer/analyzer.go"
    click Runner "https://github.com/zupit/horusec/blob/main/internal/controllers/analyzer/runner.go"
    click LangDetect "https://github.com/zupit/horusec/blob/main/internal/controllers/language_detect/language_detect.go"
    click ReqChecker "https://github.com/zupit/horusec/blob/main/internal/controllers/requirements/requirements.go"
    click ResultsPrinter "https://github.com/zupit/horusec/blob/main/internal/controllers/printresults/print_results.go"
    click CLIUsecase "https://github.com/zupit/horusec/blob/main/internal/usecases/cli/cli.go"
    click Workdir "https://github.com/zupit/horusec/blob/main/internal/entities/workdir/workdir.go"
    click AnalysisData "https://github.com/zupit/horusec/blob/main/internal/entities/docker/analysis_data.go"
    click ToolsConfig "https://github.com/zupit/horusec/blob/main/internal/entities/toolsconfig/tools_config.go"
    click CustomImages "https://github.com/zupit/horusec/blob/main/internal/entities/custom_images/custom_images.go"
    click ImagesEnum "https://github.com/zupit/horusec/blob/main/internal/enums/images/images.go"
    click OutputTypeEnum "https://github.com/zupit/horusec/blob/main/internal/enums/outputtype/output_type.go"
    click ToIgnoreEnum "https://github.com/zupit/horusec/blob/main/internal/enums/toignore/to_ignore.go"
    click DockerClient "https://github.com/zupit/horusec/blob/main/internal/services/docker/client/docker_config.go"
    click DockerAPI "https://github.com/zupit/horusec/blob/main/internal/services/docker/docker_api.go"
    click GitService "https://github.com/zupit/horusec/blob/main/internal/services/git/git.go"
    click HorusecAPI "https://github.com/zupit/horusec/blob/main/internal/services/horusec_api/horus_api.go"
    click SARIFAdapter "https://github.com/zupit/horusec/blob/main/internal/services/sarif/sarif.go"
    click SonarQubeAdapter "https://github.com/zupit/horusec/blob/main/internal/services/sonarqube/sonarqube.go"
    click CustomRules "https://github.com/zupit/horusec/blob/main/internal/services/custom_rules/service.go"
    click Engines "https://github.com/zupit/horusec/tree/main/internal/services/engines"
    click Formatters "https://github.com/zupit/horusec/tree/main/internal/services/formatters"
    click Messages "https://github.com/zupit/horusec/tree/main/internal/helpers/messages"
    click FileUtil "https://github.com/zupit/horusec/blob/main/internal/utils/file/file.go"
    click JSONUtil "https://github.com/zupit/horusec/blob/main/internal/utils/json/json.go"
    click PromptUtil "https://github.com/zupit/horusec/blob/main/internal/utils/prompt/prompt.go"
    click CopyUtil "https://github.com/zupit/horusec/blob/main/internal/utils/copy/copy.go"
    click DefaultValUtil "https://github.com/zupit/horusec/blob/main/internal/utils/valueordefault/value_or_default.go"
    click VulnHash "https://github.com/zupit/horusec/blob/main/internal/utils/vuln_hash/vuln_hash.go"
    click TestUtils "https://github.com/zupit/horusec/tree/main/internal/utils/testutil"

    %% Styles
    classDef presentation fill:#E3F2FD,stroke:#2196F3,color:#0D47A1;
    classDef application fill:#FFF3E0,stroke:#FB8C00,color:#E65100;
    classDef domain fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20;
    classDef infra fill:#F3E5F5,stroke:#AB47BC,color:#4A148C;
    classDef util fill:#ECEFF1,stroke:#78909C,color:#37474F;
    classDef external fill:#FFEBEE,stroke:#E53935,color:#B71C1C;
```
