# capsailer/capsailer-cli architecture

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

- Interactive diagram: https://gitdiagram.com/capsailer/capsailer-cli
- Repository: https://github.com/capsailer/capsailer-cli

## Overview

##### Project Type and Purpose
- Capsailer is a Go-based CLI tool focused on packaging Helm charts and container images into a single “bundle” and deploying them into air-gapped Kubernetes environments. It orchestrates local registry setup, bundle creation, bundle unpacking, and artifact pushing—entirely self-contained, without Docker, skopeo, or internet access on the target cluster.

##### File Structure Analysis
- Top-level “cmd/capsailer”: entry point (main.go) and subcommand definitions (commands.go).
- “pkg/…”: core modules grouped by feature:
- pkg/build: bundle creation logic (builder.go)
- pkg/deploy: registry deployment logic onto K8s (deployer.go)
- pkg/helm: chart discovery and analysis
- pkg/image: image handling (download, storage)
- pkg/registry: registry interactions (push, pull)
- pkg/utils: shared helpers (manifest loading, archiving, unpacking, progress)
- “docs/” + “.github/” + “examples/”: documentation, CI workflows, usage samples.
- Configuration: go.mod/go.sum, Makefile, mkdocs.yml for docs site, requirements.txt for MkDocs.

##### Key Architectural Patterns
- CLI + subcommand pattern (likely Cobra under the hood).
- Modular service layers: builder, deployer, registry client, manifest loader.
- Clear separation of concerns: image vs. chart vs. registry vs. file utilities.
- External integration points: Kubernetes API, Helm chart repositories, OCI registry protocols.

##### Main Components
a. User & CLI Frontend
- User invokes `capsailer [init|build|registry|push|unpack]`
- CLI parses command, delegates to internal modules.
b. Manifest Loader (pkg/utils/manifest_loader.go)
- Reads user’s YAML manifest → list of images & charts.
c. Build Pipeline (pkg/build/builder.go)
- Image Downloader (pkg/image)
- Helm Chart Analyzer & Fetcher (pkg/helm)
- Archiver (pkg/utils/archive.go) producing bundle.tar.gz
d. Air-gapped Deployment
- Registry Deployer (pkg/deploy/deployer.go) → interacts with Kubernetes API
- Registry Service (ChartMuseum for charts + OCI registry for images)
e. Push Pipeline (pkg/registry & pkg/utils/unpacker.go)
- Unpack bundle → extract images & charts
- Push to in-cluster registry and helm repo
f. External Systems
- Kubernetes cluster’s API server
- Container registry endpoint
- Helm chart repository (ChartMuseum)

##### Relationships & Data Flows
- CLI → Manifest Loader → Build Pipeline → Bundle artifact
- CLI “registry” → Registry Deployer → K8s API → Deploy registry pods + services
- CLI “push” → Unpacker → Registry Client → push images/charts to registry
- User’s Helm commands interact with deployed ChartMuseum service

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Actors
    User("User"):::external

    %% CLI Layer
    subgraph "CLI Frontend"
        direction TB
        CLI_Main["main.go"]:::cli
        CLI_Commands["commands.go"]:::cli
    end

    %% Core Services
    subgraph "Core Services"
        direction TB
        ML["Manifest Loader"]:::core
        Builder["Build Pipeline"]:::core
        ImageDL["Image Downloader"]:::core
        HelmAnalyzer["Helm Chart Analyzer"]:::core
        ChartFetcher["Helm Chart Fetcher"]:::core
        Deployer["Registry Deployer"]:::core
        RegClient["Registry Client"]:::core
    end

    %% Utility Layer
    subgraph "Utility Layer"
        direction TB
        Archiver["Archiver"]:::utils
        Unpacker["Unpacker"]:::utils
        Progress["Progress Reporter"]:::utils
    end

    %% Data Artifacts
    ManifestFile{{"manifest.yaml"}}:::data
    Bundle{{"bundle.tar.gz"}}:::data

    %% External Systems
    subgraph "External Systems"
        direction TB
        K8sAPI("Kubernetes API Server"):::external
        OCIReg("OCI Registry Endpoint"):::external
        ChartRepo("ChartMuseum Repository"):::external
    end

    %% Connections - CLI invocation
    User -->|invokes CLI| CLI_Commands
    User -->|invokes CLI| CLI_Main

    %% CLI to modules
    CLI_Commands -->|build| ML
    CLI_Commands -->|registry| Deployer
    CLI_Commands -->|push| Unpacker
    CLI_Commands -->|unpack| Unpacker

    %% Manifest and Build
    ML --> ManifestFile
    ML --> Builder
    Builder --> ImageDL
    Builder --> HelmAnalyzer
    Builder --> ChartFetcher
    ImageDL -->|downloads images| Progress
    HelmAnalyzer -->|analyzes charts| Progress
    ChartFetcher -->|fetches charts| Progress
    Builder -->|creates bundle| Archiver
    Archiver --> Bundle

    %% Deploy registry
    Deployer -->|deploys pods/services| K8sAPI

    %% Push pipeline
    Unpacker --> Bundle
    Unpacker --> RegClient
    RegClient -->|push images| OCIReg
    RegClient -->|push charts| ChartRepo

    %% Styles
    classDef cli fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef core fill:#90EE90,stroke:#333,stroke-width:1px
    classDef utils fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
    classDef data fill:#b0c4de,shape:cylinder,stroke:#333,stroke-width:1px

    %% Click Events
    click CLI_Main "https://github.com/capsailer/capsailer-cli/blob/main/cmd/capsailer/main.go"
    click CLI_Commands "https://github.com/capsailer/capsailer-cli/blob/main/cmd/capsailer/commands.go"
    click ML "https://github.com/capsailer/capsailer-cli/blob/main/pkg/utils/manifest_loader.go"
    click Builder "https://github.com/capsailer/capsailer-cli/blob/main/pkg/build/builder.go"
    click ImageDL "https://github.com/capsailer/capsailer-cli/blob/main/pkg/image/image.go"
    click HelmAnalyzer "https://github.com/capsailer/capsailer-cli/blob/main/pkg/helm/analyzer.go"
    click ChartFetcher "https://github.com/capsailer/capsailer-cli/blob/main/pkg/helm/chart.go"
    click Archiver "https://github.com/capsailer/capsailer-cli/blob/main/pkg/utils/archive.go"
    click Deployer "https://github.com/capsailer/capsailer-cli/blob/main/pkg/deploy/deployer.go"
    click RegClient "https://github.com/capsailer/capsailer-cli/blob/main/pkg/registry/registry.go"
    click Unpacker "https://github.com/capsailer/capsailer-cli/blob/main/pkg/utils/unpacker.go"
    click Progress "https://github.com/capsailer/capsailer-cli/blob/main/pkg/utils/progress.go"
```
