How cloudposse/atmos works
Main components
• CLI/User Interface Layer:
• Contains the terminal/UI aspects (see “internal/tui” and “cmd” directories) which provide the polished CLI and terminal interface for user input.
• Command Dispatcher & Routing:
• Implemented in “cmd” (with files like root.go, various subcommand files such as “aws.go”, “helmfile.go”, “terraform.go”, “workflow.go” etc.). This layer maps user commands to the appropriate functions.
• Business Logic & Core Libraries:
• Found in “pkg”, “internal/exec”, “pkg/config”, “pkg/component”, “pkg/describe”, “pkg/generate”, etc. These packages encapsulate the primary functionality such as stack processing, configuration management, templating logic, and integration with external systems (Terraform, AWS, Atlantics, vendoring capabilities).
• Integration & Plugin Layer:
• Modules like “pkg/hooks”, “pkg/vender”, and integrations with external services (AWS, Spacelift, Git, etc.) provide the connectivity and extensibility. This layer also covers custom commands, vendoring, and policy enforcement.
• Configuration & Orchestration:
• Handling and parsing of YAML-based definitions for stacks and components (spread across “examples”, “stacks”, “tests/fixtures/scenarios”, and also within core packages) that store the DRY configuration logic.
• Testing and Examples:
• Although not part of the runtime design, the “tests” and “examples” directories reside in their own grouping to validate and demonstrate architecture usage.
• Documentation and Website:
• The “website” directory and related docs (under “docs” and “website”) provide extensive user documentation, command examples, and design pattern guides.
Out relationships and data flows
• User Input flows from the CLI layer (terminal/UI via “internal/tui” and “cmd”) into the Command Dispatcher.
• The Dispatcher interacts with the Business Logic layer (modules in “pkg” and “internal/exec”) that load, parse, and process YAML configurations (stacks, components, and templates).
• From there, the system orchestrates operations such as generating Terraform backend configurations, varfile creation, or invoking integrations with external systems (AWS, Helmfile, etc.).
• Additionally, the plugin layer (hooks and vendoring) acts as an intermediary to pull in external dependencies or enforce custom policies (for example, via OPA or other configuration validations).
• Test and example setups simulate these flows, confirming that user commands produce proper transformations and orchestration.
Architectural patterns and design principles
• Modular Command Architecture: Each CLI command has its own file/module in the “cmd” directory. It leverages the separation-of-concerns by delegating business logic to internal libraries.
• Layered Approach: Separate clearly between the Presentation Layer (CLI/TUI), Application Logic (command dispatching, configuration parsing, orchestration), and Integration Services (Terraform, AWS, Git, etc.).
• Extensibility: The system is designed using plugin concepts (hooks, custom commands, vendoring) that allow third-party extensions and policy checks.