# argoproj/argo-helm architecture

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

- Interactive diagram: https://gitdiagram.com/argoproj/argo-helm
- Repository: https://github.com/argoproj/argo-helm

## Overview

##### Project type and purpose
- This is an open-source **Helm chart repository** (“Argo Helm Charts”) that packages, versions, and publishes Kubernetes manifests (CRDs and resources) for several Argo projects (argo-cd, argo-workflows, argo-events, argo-rollouts, argocd-apps, argocd-image-updater).
- The primary purpose is to maintain community-driven Helm charts, run CI checks (lint, test, publish), and host them on GitHub Pages / OCI registry for users to install into their Kubernetes clusters.

##### File structure
- Top-level folders:
- **charts/** – each subdirectory is a Helm chart (argo-cd, argo-events, etc.).
- **scripts/** – helper scripts for docs generation, linting, release analysis, version bumps.
- **.github/** – GitHub workflows for CI (lint/test/publish), issue templates, dependabot.
- Root config files (renovate.json, CODEOWNERS, Security, CONTRIBUTING, README).
- Within each **charts/<chart-name>/**:
- **Chart.yaml**, **values.yaml** – metadata & defaults
- **templates/** – Kubernetes manifest templates grouped by component (controller, server, CRDs, etc.)
- **crds/** (sometimes) vs. templates/crds/ – custom resource definitions
- **ci/** – chart-specific test values
- Scripts under **scripts/release-analysis/** gather and analyze upstream releases.

##### README for additional insights
- Confirms that CRDs are managed under templates to allow upgrades.
- References to Helm Capabilities (conditional templating based on Kubernetes API versions).
- Instructions for users integrating the charts via Helm CLI, helmfile, or Kustomize.

a. Main components:
- **GitHub Repository** (root of charts, scripts, workflows)
- **CI/CD Pipelines** (GitHub Actions: lint-and-test, publish)
- **Chart Modules** (each chart folder with sub-components)
- **OCI Registry / GitHub Pages** (chart hosting endpoint)
- **Users / Tooling** (Helm CLI, helmfile, Kustomize)
- **Kubernetes Clusters** (target environment where charts are deployed)
- **External Upstream Projects** (argo-cd, argo-workflows, etc., for CRD sources)
b. Relationships & interactions:
- Developer → pushes commits → CI workflows run lint/test → on success generate chart packages → publish to OCI/GitHub Pages.
- User tools (helm CLI, helmfile, Kustomize) pull charts from the registry → render templates (with `.Capabilities`) → install into Kubernetes cluster → results in K8s resources (Deployments, Services, CRDs).
- scripts/release-analysis periodically pull upstream release data → generate analytics.
c. Architectural patterns & design principles:
- **Modularization**: one chart per Argo project, each chart subdivides templates by function (controllers, webhooks, server, CRDs).
- **CI-as-Code**: GitHub Actions define lint/test/publish stages.
- **Template-Driven Deployment**: leverage Helm’s templating engine and built-in Capabilities object.
- **Separation of Concerns**: CRDs vs. non-CRDs; chart values vs. templates vs. scripts.
d. Key technologies & libraries:
- Helm (Capabilities, chart hooks, templating)
- Kubernetes API objects (CRDs, Deployments, Services, RBAC)
- GitHub Actions for CI/CD
- Python scripts & Mega-Linter for release analysis
- Renovate for dependency management

##### Elements
- **Clear labels**: e.g., “GitHub Repo”, “Helm Chart: argo-cd”, “GitHub Action: publish”, “Helm CLI”, “K8s Cluster”
- Commits → CI workflows
- CI workflows → Chart registry
- Helm CLI → Registry → Kubernetes
- scripts → release-analysis reports
- Purple for external services (OCI registry, Kubernetes cluster)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Entities
    Developer["Developer"]:::external
    Upstream["External Upstream Projects<br/>(argo-cd, argo-workflows, etc.)"]:::external

    %% Repository Layer
    subgraph "GitHub Repository" 
        Repo["/ (Argo Helm Charts Repo)"]:::repo
        click Repo "https://github.com/argoproj/argo-helm/tree/main//"
        workflows["CI/CD Pipelines<br/>(GitHub Actions)"]:::ci
        click workflows "https://github.com/argoproj/argo-helm/blob/main//.github/workflows/lint-and-test.yml"
        click workflows "https://github.com/argoproj/argo-helm/blob/main//.github/workflows/publish.yml"
        click workflows "https://github.com/argoproj/argo-helm/blob/main//.github/workflows/renovate.yaml"
        configs["Dependabot & Renovate"]:::ci
        click configs "https://github.com/argoproj/argo-helm/blob/main//.github/configs/renovate-config.js"
        click configs "https://github.com/argoproj/argo-helm/blob/main//.github/dependabot.yml"
        governance["Governance & Guides"]:::repo
        click governance "https://github.com/argoproj/argo-helm/blob/main//CODE_OF_CONDUCT.md"
        click governance "https://github.com/argoproj/argo-helm/blob/main//CONTRIBUTING.md"
        click governance "https://github.com/argoproj/argo-helm/tree/main//.github/CODEOWNERS"
        rootConfig["Root Config Files"]:::repo
        click rootConfig "https://github.com/argoproj/argo-helm/blob/main//renovate.json"
    end

    %% Release Analysis Scripts
    subgraph "Release Analysis" 
        analysisMain["main.py"]:::script
        click analysisMain "https://github.com/argoproj/argo-helm/blob/main//scripts/release-analysis/main.py"
        fetchReleases["fetch_releases.py<br/>fetch_helmet_releases.py"]:::script
        click fetchReleases "https://github.com/argoproj/argo-helm/blob/main//scripts/release-analysis/fetch_releases.py"
        click fetchReleases "https://github.com/argoproj/argo-helm/blob/main//scripts/release-analysis/fetch_helmet_releases.py"
        merge["merge_csvs.py"]:::script
        click merge "https://github.com/argoproj/argo-helm/blob/main//scripts/release-analysis/merge_csvs.py"
        plot["plot_graph.py"]:::script
        click plot "https://github.com/argoproj/argo-helm/blob/main//scripts/release-analysis/plot_graph.py"
        dockerfile["Dockerfile"]:::script
        click dockerfile "https://github.com/argoproj/argo-helm/tree/main//scripts/release-analysis/Dockerfile"
    end

    %% Helper Scripts
    subgraph "Helper Scripts" 
        docsGen["helm-docs.sh"]:::script
        click docsGen "https://github.com/argoproj/argo-helm/blob/main//scripts/helm-docs.sh"
        lintScript["lint.sh"]:::script
        click lintScript "https://github.com/argoproj/argo-helm/blob/main//scripts/lint.sh"
        bump["renovate-bump-version.sh"]:::script
        click bump "https://github.com/argoproj/argo-helm/blob/main//scripts/renovate-bump-version.sh"
    end

    %% Chart Modules
    subgraph "Helm Charts" 
        direction TB
        argoCD["argo-cd Chart"]:::chart
        click argoCD "https://github.com/argoproj/argo-helm/tree/main//charts/argo-cd"
        argoEvents["argo-events Chart"]:::chart
        click argoEvents "https://github.com/argoproj/argo-helm/tree/main//charts/argo-events"
        argoRollouts["argo-rollouts Chart"]:::chart
        click argoRollouts "https://github.com/argoproj/argo-helm/tree/main//charts/argo-rollouts"
        argoWorkflows["argo-workflows Chart"]:::chart
        click argoWorkflows "https://github.com/argoproj/argo-helm/tree/main//charts/argo-workflows"
        argocdApps["argocd-apps Chart"]:::chart
        click argocdApps "https://github.com/argoproj/argo-helm/tree/main//charts/argocd-apps"
        imageUpdater["argocd-image-updater Chart"]:::chart
        click imageUpdater "https://github.com/argoproj/argo-helm/tree/main//charts/argocd-image-updater"
    end

    %% Zoom into one chart
    subgraph "argo-cd Chart Structure" 
        direction TB
        metadata["Chart.yaml<br/>values.yaml"]:::metadata
        click metadata "https://github.com/argoproj/argo-helm/blob/main//charts/argo-cd/Chart.yaml"
        click metadata "https://github.com/argoproj/argo-helm/blob/main//charts/argo-cd/values.yaml"
        templates["templates/"]:::chart
        click templates "https://github.com/argoproj/argo-helm/blob/main//charts/argo-cd/templates/_helpers.tpl"
        click templates "https://github.com/argoproj/argo-helm/blob/main//charts/argo-cd/templates/_versions.tpl"
        crdsTpl["templates/crds/*.yaml"]:::chart
        click crdsTpl "https://github.com/argoproj/argo-helm/tree/main//charts/argo-cd/templates/crds/"
        crdsDir["crds/ (optional)"]:::chart
        click crdsDir "https://github.com/argoproj/argo-helm/tree/main//charts/argo-cd/crds/"
        ciValues["ci/*.yaml"]:::chart
        click ciValues "https://github.com/argoproj/argo-helm/tree/main//charts/argo-cd/ci/"
    end

    %% Registry & Hosting
    subgraph "Hosting" 
        registry["OCI Registry / GitHub Pages"]:::service
    end

    %% User and Deployment
    subgraph "Users & Tools" 
        helmCLI["Helm CLI"]:::external
        helmfile["helmfile"]:::optional
        kustomize["Kustomize<br/>(--api-versions)"]:::optional
        click helmCLI "https://github.com/argoproj/argo-helm/tree/main/#"
        click helmfile "https://github.com/argoproj/argo-helm/tree/main/#"
        click kustomize "https://github.com/argoproj/argo-helm/tree/main/#"
    end

    subgraph "Kubernetes Cluster" 
        k8s["K8s Cluster"]:::service
    end

    %% Relationships
    Developer -->|push commits| Repo
    Upstream -->|release data| analysisMain
    Repo -->|triggers| workflows
    workflows -->|runs scripts| lintScript
    workflows -->|runs tests| ciValues
    workflows -->|publishes charts| registry
    analysisMain -->|analyzes| merge
    merge --> plot
    docsGen --> Repo
    bump --> Repo
    registry --> helmCLI
    registry --> helmfile
    registry --> kustomize
    helmCLI -->|pull charts| registry
    helmCLI -->|deploy| k8s
    kustomize -->|render & deploy| k8s

    %% Styling
    classDef external fill:#D3D3F9,stroke:#333,stroke-width:1px;
    classDef repo fill:#B3CDE3,stroke:#333,stroke-width:1px;
    classDef ci fill:#C7E9C0,stroke:#333,stroke-width:1px;
    classDef chart fill:#FDD0A2,stroke:#333,stroke-width:1px;
    classDef metadata fill:#FDAE6B,stroke:#333,stroke-width:1px;
    classDef script fill:#E5C494,stroke:#333,stroke-width:1px;
    classDef service fill:#BC80BD,stroke:#333,stroke-width:1px;
    classDef optional fill:#E0E0E0,stroke-dasharray: 5 5,stroke:#333,stroke-width:1px;
```
