# cloudposse/atmos architecture

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

- Interactive diagram: https://gitdiagram.com/cloudposse/atmos
- Repository: https://github.com/cloudposse/atmos

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Layers
    User("User"):::user
    CLI("CLI Interface"):::cli
    Dispatcher("Command Dispatcher"):::dispatcher
    Engine("Business Logic & Core Libraries"):::engine

    %% Subgraph for Integration & Plugin Layer
    subgraph "Integration & Plugin"
        Hooks("Hooks"):::integration
        Vendoring("Vendoring"):::integration
        Cloud("Cloud Integrations"):::integration
    end

    %% Subgraph for Configuration & Orchestration
    subgraph "Configuration & Orchestration"
        GlobalConfig("Global Config"):::config
        YAMLStacks("YAML Stacks"):::config
        TestScenarios("Test Scenarios"):::config
    end

    %% Subgraph for Testing and Examples
    subgraph "Testing & Examples"
        Tests("Tests"):::testing
        Examples("Examples"):::testing
    end

    %% Subgraph for Documentation and Website
    subgraph "Documentation & Website"
        Docs("Docs"):::docs
        Website("Website"):::docs
    end

    %% Data Flow
    User -->|"initiates"| CLI
    CLI -->|"routes to"| Dispatcher
    Dispatcher -->|"triggers"| Engine
    Engine -->|"invokes"| Hooks
    Engine -->|"invokes"| Vendoring
    Engine -->|"invokes"| Cloud

    GlobalConfig -->|"loads"| Engine
    YAMLStacks -->|"feeds"| Engine
    TestScenarios -->|"feeds"| Engine

    Tests ---|"verifies"| Engine
    Examples ---|"demonstrates"| Engine
    Docs ---|"guides"| User
    Website ---|"guides"| User

    %% Click Events
    click CLI "https://github.com/cloudposse/atmos/blob/main/internal/tui/atmos/tui.go"
    click Dispatcher "https://github.com/cloudposse/atmos/blob/main/cmd/root.go"
    click Engine "https://github.com/cloudposse/atmos/tree/main/pkg/"
    click Hooks "https://github.com/cloudposse/atmos/tree/main/pkg/hooks/"
    click Vendoring "https://github.com/cloudposse/atmos/tree/main/pkg/vender/"
    click Cloud "https://github.com/cloudposse/atmos/tree/main/pkg/aws/"
    click GlobalConfig "https://github.com/cloudposse/atmos/blob/main/atmos.yaml"
    click YAMLStacks "https://github.com/cloudposse/atmos/tree/main/examples/"
    click TestScenarios "https://github.com/cloudposse/atmos/tree/main/tests/fixtures/scenarios/"
    click Tests "https://github.com/cloudposse/atmos/tree/main/tests/"
    click Examples "https://github.com/cloudposse/atmos/tree/main/examples/"
    click Docs "https://github.com/cloudposse/atmos/tree/main/docs/"
    click Website "https://github.com/cloudposse/atmos/tree/main/website/"

    %% Styles
    classDef user fill:#FAD7A0,stroke:#E67E22,stroke-width:2px;
    classDef cli fill:#AED6F1,stroke:#3498DB,stroke-width:2px;
    classDef dispatcher fill:#A9DFBF,stroke:#27AE60,stroke-width:2px;
    classDef engine fill:#F9E79F,stroke:#F1C40F,stroke-width:2px;
    classDef integration fill:#F5B7B1,stroke:#E74C3C,stroke-width:2px;
    classDef config fill:#D2B4DE,stroke:#8E44AD,stroke-width:2px;
    classDef testing fill:#ABEBC6,stroke:#16A085,stroke-width:2px;
    classDef docs fill:#D5F5E3,stroke:#2ECC71,stroke-width:2px;
```
