# bitnami/charts-syncer architecture

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

- Interactive diagram: https://gitdiagram.com/bitnami/charts-syncer
- Repository: https://github.com/bitnami/charts-syncer

## Overview

##### Project type and purpose
- This is a Go-based command-line tool (“charts-syncer”) whose job is to synchronize Helm chart packages and their associated container images between source and target repositories (Helm, OCI, ChartMuseum, Harbor, local).
- It can operate online or “air-gapped” via a two-step download-and-upload flow and can be run manually or as a Kubernetes CronJob.

##### File structure
- Top-level:
- cmd/       – the CLI entrypoint and commands (main.go, sync.go, version.go)
- api/       – Protobuf definitions and generated Go code for configuration and index artifacts
- internal/  – internal packages (config loader, cache, indexer, logging, utilities)
- pkg/       – the core library:
· pkg/client – pluggable clients for source/target chart and OCI registries
· pkg/syncer – the orchestration logic to sync charts/images
- deployment/– Kubernetes CronJob manifests and Kustomize config
- docs/, examples/, test/ – supporting documentation, samples, and end-to-end scripts
- Presence of Protobuf files (api/config.proto, internal/indexer/api/index.proto) indicates a strongly-typed config & index format.
- Makefile, Dockerfile, Go modules and GitHub workflows define build, CI, release and deployment.

##### README for additional insights
- Describes “sync” use cases, advanced flags, supported repository kinds, two-step air-gap mode.
- Mentions a Kubernetes CronJob for scheduled synchronization.
- Confirms key architectural pieces: source repo, target repo, chart packaging, image relocation, config loader.

##### Components
a. Main components
- CLI Frontend (cmd/*.go)
- Configuration Loader (internal/config)
- Sync Orchestrator (pkg/syncer)
- Indexer (internal/indexer)
- Chart-client plugins (pkg/client/repo/*)
- Container-registry client plugins (pkg/client/repo/*/oci)
- Cache (internal/cache)
- Utilities & Logging (internal/utils, internal/log)
- Kubernetes CronJob (deployment/cronjob.yaml)
- External Services: Source Helm/OCI/ChartMuseum/Harbor, Target Helm/OCI, Container Registry

b. Relationships & interactions
1. User invokes the CLI (charts-syncer sync) or CronJob triggers it.
2. CLI parses flags and loads config via Protobuf (api/config.pb.go → internal/config).
3. Sync Orchestrator (pkg/syncer):
– Uses Indexer to fetch/parse chart index from source repo.
– Iterates charts: for each, uses chart-client plugin to download chart package.
– Extracts and rewrites chart metadata (values.yaml, Chart.yaml, Images.lock) via internal/utils.
– Uses container-registry client plugin to pull and push image layers (unless skipImages).
– Uses chart-client plugin to push modified chart package to target.
– Caches downloads in internal/cache.
– Logs progress via internal/log.
4. On air-gap mode: orchestrator writes files to local disk (LOCAL target), to be uploaded in a second step.

c. Architectural patterns & design principles
- Layered modular design: cmd → internal → pkg → external plugins
- Dependency injection via interfaces in pkg/client to support multiple repo kinds
- Protobuf for strongly-typed config and index serialization
- Separation of concerns: indexing, chart transformation, image relocation
- Cache abstraction to support in-memory or on-disk caching

d. Relevant technologies, frameworks, libraries
- Go modules (go.mod), Protobuf (prototool.yaml)
- Kubernetes CronJob for scheduled runs
- Helm repo clients, OCI registry APIs
- Kustomize for deployment manifests
- GitHub Actions, goreleaser for CI/CD
- Docker container (Dockerfile)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Kubernetes CronJob Wrapper
    subgraph "Kubernetes CronJob" 
        direction TB
        CronJob["CronJob"]:::infra
        CronJob -->|triggers| CLI_Main
    end

    %% CLI Layer
    subgraph "CLI Layer"
        direction LR
        CLI_Main["main.go"]:::cli
        CLI_Root["root.go"]:::cli
        CLI_Sync["sync.go"]:::cli
        CLI_Version["version.go"]:::cli
    end

    %% Config Loader Layer
    subgraph "Config Loader" 
        direction LR
        Proto_Config["config.proto"]:::config
        PB_Config["config.pb.go"]:::config
        API_Config["config.go"]:::config
        Internal_Config["internal/config.go"]:::config
    end

    %% Core Orchestrator
    subgraph "Sync Orchestrator" 
        direction LR
        Syncer_Core["syncer.go"]:::core
        Syncer_Sync["sync.go"]:::core
        Syncer_Index["index.go"]:::core
        Syncer_Workdir["workdir.go"]:::core
    end

    %% Indexer
    subgraph "Indexer"
        direction LR
        IDX_Core["indexer.go"]:::core
        IDX_Proto["index.proto"]:::config
        IDX_PB["index.pb.go"]:::config
        IDX_OCI["oci.go"]:::core
        IDX_Resolver["resolver.go"]:::core
    end

    %% Cache
    subgraph "Cache Layer"
        direction LR
        Cache_Mem["cache.go"]:::core
        Cache_Disk["cachedisk.go"]:::core
    end

    %% Utilities & Logging
    subgraph "Utilities & Logging"
        direction LR
        Utils["utils.go"]:::core
        Log_Main["logger.go"]:::core
        Log_Section["section_logger.go"]:::core
    end

    %% Plugin Layer
    subgraph "Chart Client Plugins"
        direction LR
        Plugin_ChartMuseum["chartmuseum.go"]:::plugin
        Plugin_Harbor["harbor.go"]:::plugin
        Plugin_Helm["helmclassic.go"]:::plugin
        Plugin_Local["local.go"]:::plugin
    end

    OCI_Plugin["oci.go"]:::plugin
    Client_Core["core.go"]:::plugin
    Client_Client["client.go"]:::plugin

    %% External Services
    subgraph "External Repositories"
        direction LR
        Src_Helm["Helm Repo"]:::external
        Src_OCI["OCI Registry"]:::external
        Src_CM["ChartMuseum"]:::external
        Src_Harbor["Harbor"]:::external
        Target_Helm["Helm Repo"]:::external
        Target_OCI["OCI Registry"]:::external
        Local_FS["Local Disk"]:::external
    end

    %% CronJob -> CLI already above
    %% Flows
    CLI_Main -->|uses| Proto_Config
    CLI_Main -->|uses| Internal_Config
    Proto_Config --> PB_Config
    PB_Config --> API_Config
    API_Config --> Internal_Config

    CLI_Sync -->|loads| Internal_Config
    CLI_Sync -->|invokes| Syncer_Core

    Syncer_Core -->|uses| Syncer_Index
    Syncer_Core -->|uses| Syncer_Sync
    Syncer_Core -->|uses| Syncer_Workdir
    Syncer_Core -->|calls| IDX_Core
    Syncer_Core -->|caches via| Cache_Mem
    Syncer_Core -->|caches via| Cache_Disk
    Syncer_Core -->|logs via| Log_Main
    Syncer_Core -->|logs via| Log_Section
    Syncer_Core -->|transforms via| Utils

    Syncer_Core -->|downloads charts| Plugin_ChartMuseum
    Syncer_Core -->|downloads charts| Plugin_Harbor
    Syncer_Core -->|downloads charts| Plugin_Helm
    Syncer_Core -->|downloads charts| Plugin_Local

    Syncer_Core -->|relocates images| OCI_Plugin

    Plugin_ChartMuseum -->|source| Src_CM
    Plugin_Harbor -->|source| Src_Harbor
    Plugin_Helm -->|source| Src_Helm
    Plugin_Local -->|source| Local_FS

    OCI_Plugin -->|source/push| Src_OCI

    Syncer_Core -->|push charts| Plugin_ChartMuseum
    Syncer_Core -->|push charts| Plugin_Harbor
    Syncer_Core -->|push charts| Plugin_Helm
    Syncer_Core -->|push charts| Plugin_Local

    Syncer_Core -->|push images| OCI_Plugin
    OCI_Plugin -->|target| Target_OCI
    Plugin_ChartMuseum -->|target| Target_Helm
    Plugin_Harbor -->|target| Target_Helm
    Plugin_Helm -->|target| Target_Helm
    Plugin_Local -->|target| Local_FS

    %% Click Events
    click CLI_Main "https://github.com/bitnami/charts-syncer/blob/v2/cmd/main.go"
    click CLI_Root "https://github.com/bitnami/charts-syncer/blob/v2/cmd/root.go"
    click CLI_Sync "https://github.com/bitnami/charts-syncer/blob/v2/cmd/sync.go"
    click CLI_Version "https://github.com/bitnami/charts-syncer/blob/v2/cmd/version.go"

    click Proto_Config "https://github.com/bitnami/charts-syncer/blob/v2/api/config.proto"
    click PB_Config "https://github.com/bitnami/charts-syncer/blob/v2/api/config.pb.go"
    click API_Config "https://github.com/bitnami/charts-syncer/blob/v2/api/config.go"
    click Internal_Config "https://github.com/bitnami/charts-syncer/blob/v2/internal/config/config.go"

    click Syncer_Core "https://github.com/bitnami/charts-syncer/blob/v2/pkg/syncer/syncer.go"
    click Syncer_Sync "https://github.com/bitnami/charts-syncer/blob/v2/pkg/syncer/sync.go"
    click Syncer_Index "https://github.com/bitnami/charts-syncer/blob/v2/pkg/syncer/index.go"
    click Syncer_Workdir "https://github.com/bitnami/charts-syncer/blob/v2/pkg/syncer/workdir.go"

    click IDX_Core "https://github.com/bitnami/charts-syncer/blob/v2/internal/indexer/indexer.go"
    click IDX_Proto "https://github.com/bitnami/charts-syncer/blob/v2/internal/indexer/api/index.proto"
    click IDX_PB "https://github.com/bitnami/charts-syncer/blob/v2/internal/indexer/api/index.pb.go"
    click IDX_OCI "https://github.com/bitnami/charts-syncer/blob/v2/internal/indexer/oci.go"
    click IDX_Resolver "https://github.com/bitnami/charts-syncer/blob/v2/internal/indexer/resolver.go"

    click Plugin_ChartMuseum "https://github.com/bitnami/charts-syncer/blob/v2/pkg/client/repo/chartmuseum/chartmuseum.go"
    click Plugin_Harbor "https://github.com/bitnami/charts-syncer/blob/v2/pkg/client/repo/harbor/harbor.go"
    click Plugin_Helm "https://github.com/bitnami/charts-syncer/blob/v2/pkg/client/repo/helmclassic/helmclassic.go"
    click Plugin_Local "https://github.com/bitnami/charts-syncer/blob/v2/pkg/client/repo/local/local.go"

    click OCI_Plugin "https://github.com/bitnami/charts-syncer/blob/v2/pkg/client/repo/oci/oci.go"
    click Client_Core "https://github.com/bitnami/charts-syncer/blob/v2/pkg/client/repo/core.go"
    click Client_Client "https://github.com/bitnami/charts-syncer/blob/v2/pkg/client/client.go"

    click Cache_Mem "https://github.com/bitnami/charts-syncer/blob/v2/internal/cache/cache.go"
    click Cache_Disk "https://github.com/bitnami/charts-syncer/blob/v2/internal/cache/cachedisk/cachedisk.go"

    click Utils "https://github.com/bitnami/charts-syncer/blob/v2/internal/utils/utils.go"
    click Log_Main "https://github.com/bitnami/charts-syncer/blob/v2/internal/log/logger.go"
    click Log_Section "https://github.com/bitnami/charts-syncer/blob/v2/internal/log/section_logger.go"

    click CronJob "https://github.com/bitnami/charts-syncer/blob/v2/deployment/cronjob.yaml"
    click CronJob "https://github.com/bitnami/charts-syncer/blob/v2/deployment/kustomization.yaml"

    %% Styles
    classDef cli fill:#E0F7FA,stroke:#006064,color:#006064
    classDef config fill:#E3F2FD,stroke:#0D47A1,color:#0D47A1
    classDef core fill:#E8F5E9,stroke:#1B5E20,color:#1B5E20
    classDef plugin fill:#FFF3E0,stroke:#E65100,color:#E65100
    classDef external fill:#ECEFF1,stroke:#455A64,color:#455A64
    classDef infra fill:#F3E5F5,stroke:#4A148C,color:#4A148C
```
