# roboll/helmfile architecture

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

- Interactive diagram: https://gitdiagram.com/roboll/helmfile
- Repository: https://github.com/roboll/helmfile

## Overview

##### Project type and purpose
- This is a Go-based CLI tool (“helmfile”) that orchestrates Helm chart releases across environments.
- It reads one or more Helmfile yamls, computes desired release state, and invokes Helm under the hood.

##### File structure
- Entry point: main.go (CLI bootstrap).
- pkg/app – command implementation and orchestration.
- pkg/argparser – CLI flag parsing.
- pkg/state – domain logic: load environment, chart dependencies, compute state.
- pkg/tmpl – templating engine (Go text templates + Sprig + secret expansion).
- pkg/helmexec – abstraction over invoking `helm` subprocess.
- pkg/remote – support for remote charts or config.
- pkg/plugins – pluggable value sources.
- pkg/event – event bus for logging/telemetry.
- scripts and hooks – pre/post build and CI pipeline.
- examples, docs, tests – illustrate usage and verify correctness.

##### Core architecture and component identification
a. CLI Layer
– Component: main.go + pkg/argparser
– Responsibility: parse user input, commands (sync, apply, diff, destroy).
b. Application Orchestrator
– Component: pkg/app
– Responsibility: coordinate loading of config, templating, state computation, helm execution.
c. Configuration & Environment Loader
– Component: pkg/app/config.go + pkg/environment
– Responsibility: read Helmfile, environment overrides, remote includes.
d. Templating Engine
– Component: pkg/tmpl + two-pass renderer
– Responsibility: render Helmfile/Gotemplate and inline secrets.
e. State Manager
– Component: pkg/state
– Responsibility: build desired release graph, filter by selectors, reconcile with cluster (helmfile.diff).
f. Helm Executor
– Component: pkg/helmexec + pkg/exectest
– Responsibility: shell out to `helm` CLI, capture logs, errors.
g. Plugins & Remote Integrations
– Component: pkg/plugins + pkg/remote
– Responsibility: fetch additional values, decrypt secrets, integrate with vault/Git.
h. Event & Logging
– Component: pkg/event
– Responsibility: publish events (start step, success, failure) for uniform logging.
i. CI/CD hooks & Docker/Vagrant
– .circleci, Dockerfile, Vagrantfile
– Responsibility: containerized build/test, local dev environments.

##### Relationships and data flow
– User invokes CLI (main.go) → argparser builds Cmd object → app.Run()
– app loads config via environment & config loader → passes raw YAML through tmpl rendering
– state manager receives rendered config → computes desired release state → emits events
– helmexec invoked per release → events logged → results aggregated
– final exit code and optionally state snapshot/write back.

##### Architectural patterns and principles
– Layered architecture: presentation (CLI) → application → domain (state) → infrastructure (helmexec).
– Single Responsibility: each pkg handles a distinct concern.
– Dependency injection: interfaces for exec, remote, plugin to allow testing/mocking.
– Event-driven logging: centralized event bus.

##### Final checklist
- All main components present and clearly labeled.
- Callouts for important design principles (DI, event bus, layered separation).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Swimlanes
    subgraph "CLI Layer"
        direction TB
        Main["CLI: main.go"]:::cli
        ArgParser["Argparser"]:::cli
    end

    subgraph "Core Library"
        direction TB
        App["App Orchestrator"]:::core
        Config["Config/Env Loader"]:::core
        Templater["Templating Engine"]:::core
        StateManager["State Manager"]:::core
        HelmExec["Helm Executor"]:::core
        Plugins["Plugins & Remote"]:::core
        EventBus["Event Bus/Logger"]:::core
    end

    subgraph "Infrastructure & CI/CD"
        direction TB
        YAMLConfig["Helmfile YAML"]:::infra
        HelmCLI["Helm CLI"]:::infra
        K8sAPI["Kubernetes API"]:::infra
        CIConfig[".circleci/config.yml"]:::ci
        Dockerfiles["Dockerfile(s)"]:::ci
        Vagrant["Vagrantfile"]:::ci
    end

    %% Connections
    Main --> ArgParser
    Main --> YAMLConfig
    ArgParser --> App
    App --> Config
    Config --> Templater
    Config --> Plugins
    Templater --> StateManager
    Templater --> Plugins
    StateManager --> HelmExec
    StateManager <--> K8sAPI
    HelmExec --> HelmCLI
    App --> EventBus
    StateManager --> EventBus
    HelmExec --> EventBus

    %% Click Events
    click Main "https://github.com/roboll/helmfile/blob/master/main.go"
    click ArgParser "https://github.com/roboll/helmfile/blob/master/pkg/argparser/args.go"
    click App "https://github.com/roboll/helmfile/blob/master/pkg/app/app.go"
    click Config "https://github.com/roboll/helmfile/blob/master/pkg/app/config.go"
    click Config "https://github.com/roboll/helmfile/blob/master/pkg/environment/environment.go"
    click Templater "https://github.com/roboll/helmfile/blob/master/pkg/tmpl/text_renderer.go"
    click Templater "https://github.com/roboll/helmfile/blob/master/pkg/tmpl/context_tmpl.go"
    click StateManager "https://github.com/roboll/helmfile/blob/master/pkg/state/state.go"
    click StateManager "https://github.com/roboll/helmfile/blob/master/pkg/state/create.go"
    click HelmExec "https://github.com/roboll/helmfile/blob/master/pkg/helmexec/helmexec.go"
    click HelmExec "https://github.com/roboll/helmfile/blob/master/pkg/exectest/helm.go"
    click Plugins "https://github.com/roboll/helmfile/blob/master/pkg/plugins/vals.go"
    click Plugins "https://github.com/roboll/helmfile/blob/master/pkg/remote/remote.go"
    click EventBus "https://github.com/roboll/helmfile/blob/master/pkg/event/bus.go"
    click CIConfig "https://github.com/roboll/helmfile/blob/master/.circleci/config.yml"
    click Dockerfiles "https://github.com/roboll/helmfile/tree/master/Dockerfile"
    click Vagrant "https://github.com/roboll/helmfile/tree/master/Vagrantfile"

    %% Styles
    classDef cli fill:#CCE5FF,stroke:#005BAC,color:#000;
    classDef core fill:#CCF5CC,stroke:#2E8B57,color:#000;
    classDef infra fill:#FFE5CC,stroke:#D2691E,color:#000;
    classDef ci fill:#EEEEEE,stroke:#666,color:#000;
    class Main,ArgParser cli
    class App,Config,Templater,StateManager,HelmExec,Plugins,EventBus core
    class YAMLConfig,HelmCLI,K8sAPI infra
    class CIConfig,Dockerfiles,Vagrant ci
```
