How srevinsaju/togomak works
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.