# akuity/kargo-helm architecture

> Architecture diagram of the GitHub repository akuity/kargo-helm, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-26). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/akuity/kargo-helm
- Repository: https://github.com/akuity/kargo-helm

## Overview

This repository is a declarative Kargo-and-Helm GitOps example, not the guestbook application itself. Its principal workflow is detecting a new image as Freight, promoting it through dev, staging, and prod, and applying promoted configuration changes to Git. The README also documents feature-flag promotion and direct Git commits to dev and staging. The tree identifies the Argo CD and Helm deployment configuration, but no source excerpts were provided, so their detailed wiring is not inferred.

Main entry points: [`kargo/promotiontask.yaml`](https://github.com/akuity/kargo-helm/blob/main/kargo/promotiontask.yaml) (Promotion task), [`kargo/warehouse.yaml`](https://github.com/akuity/kargo-helm/blob/main/kargo/warehouse.yaml) (Warehouse), [`kargo/stages.yaml`](https://github.com/akuity/kargo-helm/blob/main/kargo/stages.yaml) (Promotion stages), [`charts/guestbook`](https://github.com/akuity/kargo-helm/tree/main/charts/guestbook) (Guestbook Helm chart)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_promotion["Kargo promotion"]
  node_kargo_project["Kargo project<br/>[project.yaml]"]
  node_warehouse["Warehouse<br/>[warehouse.yaml]"]
  node_freight["Image Freight"]
  node_stages["Promotion stages<br/>[stages.yaml]"]
  node_promotion_task["Promotion task<br/>[promotiontask.yaml]"]
end

subgraph group_configuration["Deployment configuration"]
  node_base_flags["Base feature flags<br/>[feature-flags.yaml]"]
  node_environment_values["Environment values"]
  node_environment_flags["Environment flags"]
  node_guestbook_chart["Guestbook Helm chart"]
end

subgraph group_delivery["GitOps delivery"]
  node_argocd_appset["Argo CD app set<br/>[appset.yaml]"]
  node_argocd_project["Argo CD project<br/>[appproj.yaml]"]
end

node_operator(("Kargo operator"))
node_container_registry[("Container registry")]
node_git_repo[("Git repository")]
node_deployment["Guestbook deployment"]

node_operator -->|"selects for promotion"| node_freight
node_warehouse -->|"monitors images"| node_container_registry
node_warehouse -->|"detects images"| node_freight
node_operator -->|"promotes through"| node_stages
node_stages -->|"uses task"| node_promotion_task
node_promotion_task -->|"commits changes"| node_git_repo
node_promotion_task -->|"promotes flags"| node_base_flags
node_git_repo -->|"holds environment config"| node_environment_values
node_git_repo -->|"holds environment flags"| node_environment_flags
node_argocd_appset -->|"configures application"| node_guestbook_chart
node_argocd_project -->|"defines project"| node_argocd_appset
node_guestbook_chart -->|"renders manifests"| node_deployment

click node_kargo_project "https://github.com/akuity/kargo-helm/blob/main/kargo/project.yaml"
click node_warehouse "https://github.com/akuity/kargo-helm/blob/main/kargo/warehouse.yaml"
click node_stages "https://github.com/akuity/kargo-helm/blob/main/kargo/stages.yaml"
click node_promotion_task "https://github.com/akuity/kargo-helm/blob/main/kargo/promotiontask.yaml"
click node_base_flags "https://github.com/akuity/kargo-helm/blob/main/base/feature-flags.yaml"
click node_environment_values "https://github.com/akuity/kargo-helm/tree/main/env"
click node_environment_flags "https://github.com/akuity/kargo-helm/tree/main/env"
click node_guestbook_chart "https://github.com/akuity/kargo-helm/tree/main/charts/guestbook"
click node_argocd_appset "https://github.com/akuity/kargo-helm/blob/main/argocd/appset.yaml"
click node_argocd_project "https://github.com/akuity/kargo-helm/blob/main/argocd/appproj.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_kargo_project,node_warehouse,node_freight,node_stages,node_promotion_task toneBlue
class node_base_flags,node_environment_values,node_environment_flags,node_guestbook_chart,node_container_registry,node_git_repo toneAmber
class node_argocd_appset,node_argocd_project toneMint
class node_operator,node_deployment toneIndigo
```

## Components

### Kargo promotion

- [Kargo project](https://github.com/akuity/kargo-helm/blob/main/kargo/project.yaml): `kargo/project.yaml`
- [Warehouse](https://github.com/akuity/kargo-helm/blob/main/kargo/warehouse.yaml): `kargo/warehouse.yaml`
- **Image Freight**
- [Promotion stages](https://github.com/akuity/kargo-helm/blob/main/kargo/stages.yaml): `kargo/stages.yaml`
- [Promotion task](https://github.com/akuity/kargo-helm/blob/main/kargo/promotiontask.yaml): `kargo/promotiontask.yaml`

### Deployment configuration

- [Base feature flags](https://github.com/akuity/kargo-helm/blob/main/base/feature-flags.yaml): `base/feature-flags.yaml`
- [Environment values](https://github.com/akuity/kargo-helm/tree/main/env): `env`
- [Environment flags](https://github.com/akuity/kargo-helm/tree/main/env): `env`
- [Guestbook Helm chart](https://github.com/akuity/kargo-helm/tree/main/charts/guestbook): `charts/guestbook`

### GitOps delivery

- [Argo CD app set](https://github.com/akuity/kargo-helm/blob/main/argocd/appset.yaml): `argocd/appset.yaml`
- [Argo CD project](https://github.com/akuity/kargo-helm/blob/main/argocd/appproj.yaml): `argocd/appproj.yaml`

### Other components

- **Kargo operator**
- **Container registry**
- **Git repository**
- **Guestbook deployment**

## Connections

- Kargo operator → Image Freight: selects for promotion
- Warehouse → Container registry: monitors images
- Warehouse → Image Freight: detects images
- Kargo operator → Promotion stages: promotes through
- Promotion stages → Promotion task: uses task
- Promotion task → Git repository: commits changes
- Promotion task → Base feature flags: promotes flags
- Git repository → Environment values: holds environment config
- Git repository → Environment flags: holds environment flags
- Argo CD app set → Guestbook Helm chart: configures application
- Argo CD project → Argo CD app set: defines project
- Guestbook Helm chart → Guestbook deployment: renders manifests