# srevinsaju/togomak architecture

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

- Interactive diagram: https://gitdiagram.com/srevinsaju/togomak
- Repository: https://github.com/srevinsaju/togomak

## Overview

##### Main Components
- CLI/Command Layer: Represent the primary executable (found in cmd/togomak) which accepts commands from the user. This is the entry point that triggers pipeline execution.
- Pipeline Orchestrator: Central to the tool, this component (mainly within internal/core, internal/orchestra, and internal/ci) is responsible for reading the pipeline definition (the HCL configuration), resolving dependencies (stages, modules, hooks), and coordinating the execution.
- Parser/Evaluator: Within internal/parse and internal/global/hcl, show a dedicated module that parses HCL files, interprets functions (including ones mimicking Terraform’s functions), and builds the intermediate representations used by the engine.
- Stage and Module Runner: Components inside internal/ci and internal/runnable that execute separate stages concurrently, manage pre/post hooks, lifecycle events, and handle concurrency.
- External Integrations and Third-Party Adapters: Highlight integration modules (internal/third-party) that tie togomak with systems such as Docker, Git, and Terraform. These adapt external APIs and support additional functions (e.g., terraform data, resource blocks).
- Logging and Diagnostics: Include sub-components for logging (internal/log, internal/logging, internal/ui) that assist in detailed error reporting and progress display.
- Configuration and Meta-data Management: In modules like internal/meta and internal/global, represent the components that handle configurations, environment variables, and meta arguments which alter the pipeline execution behavior.
- Testing and Examples Framework: While not necessarily running in production, the tests (tests directory, examples folder) illustrate the tool’s features and validate its workings, and can be represented as separate workflows that integrate with the CI/CD pipeline demonstration.

##### Relationships and Data Flow
- The CLI layer reads input (via command-line arguments) and loads HCL configuration files (togomak.hcl and others).
- The Parser/Evaluator converts HCL definitions into a structured model, which is then fed into the Pipeline Orchestrator.
- The Orchestrator coordinates with the Stage and Module Runner to schedule and execute stages in parallel (or based on dependency rules).
- Hooks (pre/post) are triggered around stage execution, and any external data (e.g., provider data from terraform blocks or environment variables) is processed via dedicated data modules.
- External integrations such as Docker operations and Git actions are invoked as needed during execution, often managed by third-party adapters.
- Logging and diagnostics modules intercept events at various points to record outcomes, errors, and user feedback.
- Test suites run separately as part of continuous integration to verify that these components work together correctly.

##### Architectural Patterns and Design Principles
- Concurrency and Parallel Execution: Emphasize that stages/modules run in parallel by default (unless dependencies dictate otherwise).
- Declarative Configuration: The system relies on HCL to declaratively define pipeline behavior, so include how configuration flows from disk to execution.
- Separation of Concerns: Different internal packages (e.g., orchestration, parsing, logging) are used to enforce clear responsibilities.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External User Interface
    U["User Command"]:::user

    %% Main Togomak system components
    subgraph "Togomak System"
        CLI["CLI Engine"]:::cli
        HCL["HCL Parser / Evaluator"]:::parser
        ORCH["Pipeline Orchestrator"]:::orchestrator
        STAGE["Stage and Module Runner"]:::runner
        EXT["External Integrations & Adapters"]:::external
        LOG["Logging & Diagnostics"]:::logging
        CONF["Configuration & Meta-data"]:::config
    end

    %% Testing and Examples Framework (separate component)
    TEST["Testing & Examples Framework"]:::testing

    %% Data flow
    U -->|"initiates"| CLI
    CLI -->|"readsHCLconfig"| HCL
    HCL -->|"buildsModel"| ORCH
    CONF -->|"suppliesConfig"| ORCH
    ORCH -->|"coordinatesStages"| STAGE
    STAGE -->|"triggersIntegrations"| EXT
    STAGE -->|"logsEvents"| LOG
    ORCH -->|"reportsStatus"| LOG
    CLI -->|"logsCLIEvents"| LOG
    TEST ---|"CI/CDTests"| ORCH

    %% Click Events for CLI/Command Layer
    click CLI "https://github.com/srevinsaju/togomak/blob/v2/cmd/togomak/main.go"
    click CLI "https://github.com/srevinsaju/togomak/blob/v2/cmd/togomak/utils.go"

    %% Click Events for Pipeline Orchestrator
    click ORCH "https://github.com/srevinsaju/togomak/blob/v2/internal/core/togomak.go"
    click ORCH "https://github.com/srevinsaju/togomak/blob/v2/internal/orchestra/orchestra.go"
    click ORCH "https://github.com/srevinsaju/togomak/blob/v2/internal/ci/pipeline.go"

    %% Click Events for Parser/Evaluator
    click HCL "https://github.com/srevinsaju/togomak/blob/v2/internal/parse/parse.go"
    click HCL "https://github.com/srevinsaju/togomak/blob/v2/internal/global/hcl.go"

    %% Click Events for Stage and Module Runner
    click STAGE "https://github.com/srevinsaju/togomak/blob/v2/internal/ci/stage_run.go"
    click STAGE "https://github.com/srevinsaju/togomak/blob/v2/internal/ci/module_run.go"
    click STAGE "https://github.com/srevinsaju/togomak/blob/v2/internal/runnable/options.go"
    click STAGE "https://github.com/srevinsaju/togomak/blob/v2/internal/ci/run.go"

    %% Click Events for External Integrations and Third-Party Adapters
    click EXT "https://github.com/srevinsaju/togomak/blob/v2/internal/third-party/docker/docker.go"
    click EXT "https://github.com/srevinsaju/togomak/tree/v2/internal/third-party/hashicorp/terraform/"

    %% Click Events for Logging and Diagnostics
    click LOG "https://github.com/srevinsaju/togomak/blob/v2/internal/log/logger.go"
    click LOG "https://github.com/srevinsaju/togomak/blob/v2/internal/logging/logging.go"
    click LOG "https://github.com/srevinsaju/togomak/blob/v2/internal/ui/progress.go"

    %% Click Events for Configuration and Meta-data Management
    click CONF "https://github.com/srevinsaju/togomak/blob/v2/internal/meta/app.go"
    click CONF "https://github.com/srevinsaju/togomak/blob/v2/internal/global/global.go"

    %% Click Events for Testing and Examples Framework
    click TEST "https://github.com/srevinsaju/togomak/tree/v2/tests/"
    click TEST "https://github.com/srevinsaju/togomak/tree/v2/examples/"

    %% Styles for color coding
    classDef cli fill:#AED6F1,stroke:#5DADE2,stroke-width:2px;
    classDef parser fill:#A9DFBF,stroke:#229954,stroke-width:2px;
    classDef orchestrator fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef runner fill:#F5CBA7,stroke:#E67E22,stroke-width:2px;
    classDef external fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef logging fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef config fill:#D1F2EB,stroke:#1ABC9C,stroke-width:2px;
    classDef testing fill:#D6EAF8,stroke:#3498DB,stroke-width:2px;
    classDef user fill:#FDEDEC,stroke:#E74C3C,stroke-width:2px;
```
