# argoproj/argo-cd architecture

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

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

## Overview

Argo CD is a declarative GitOps continuous-delivery platform for Kubernetes. A user defines or updates an Application through the UI, CLI, or API; the API persists the desired application configuration, the repo server obtains source content and generates manifests, and the application controller compares desired and live state and applies changes through the GitOps engine. ApplicationSets generate Applications from cluster, Git, pull-request, and other inputs; notifications, authentication, and cluster/repository management are additional product capabilities. The map reflects the provided tree, README, and sampled excerpts; some subsystem wiring is omitted where source excerpts do not establish it.

Main entry points: [`server/server.go`](https://github.com/argoproj/argo-cd/blob/master/server/server.go) (API server), [`controller/appcontroller.go`](https://github.com/argoproj/argo-cd/blob/master/controller/appcontroller.go) (Application controller), [`gitops-engine/pkg/engine/engine.go`](https://github.com/argoproj/argo-cd/blob/master/gitops-engine/pkg/engine/engine.go) (GitOps engine), [`pkg/apis/application/v1alpha1/types.go`](https://github.com/argoproj/argo-cd/blob/master/pkg/apis/application/v1alpha1/types.go) (Application resources)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["User interaction"]
  node_ui["Web UI<br/>[app.tsx]"]
  node_cli["CLI<br/>[root.go]"]
end

subgraph group_api["API and services"]
  node_server["API server<br/>[server.go]"]
  node_appsvc["Application API<br/>[application.go]"]
  node_sessions["Session service<br/>[session.go]"]
end

subgraph group_desired["Desired state"]
  node_appcr[("Application resources<br/>[types.go]")]
  node_reposerver["Repo server<br/>[server.go]"]
  node_appset["ApplicationSet controller"]
  node_generators["Application generators<br/>[interface.go]"]
end

subgraph group_reconcile["Reconciliation"]
  node_appcontroller["Application controller<br/>[appcontroller.go]"]
  node_engine["GitOps engine<br/>[engine.go]"]
  node_cache["Cluster cache<br/>[cluster.go]"]
  node_diff["Resource diff<br/>[diff.go]"]
  node_sync["Sync executor<br/>[sync_context.go]"]
  node_hydrator["Manifest hydrator<br/>[hydrator.go]"]
end

subgraph group_extensions["Product extensions"]
  node_notifications["Notifications<br/>[controller.go]"]
  node_projects["Projects and policy<br/>[project.go]"]
  node_settings["Settings service<br/>[settings.go]"]
end

node_user(("Operator"))
node_repo(("Git repositories"))
node_cluster(("Kubernetes cluster"))

node_user -->|"uses"| node_ui
node_user -->|"uses"| node_cli
node_ui -->|"calls API"| node_server
node_cli -->|"calls API"| node_server
node_server -->|"registers service"| node_appsvc
node_server -->|"registers service"| node_sessions
node_appsvc -->|"reads and writes"| node_appcr
node_appcr -->|"triggers reconcile"| node_appcontroller
node_appcontroller -->|"requests manifests"| node_reposerver
node_reposerver -->|"reads source"| node_repo
node_appcontroller -->|"syncs resources"| node_engine
node_engine -->|"reads live state"| node_cache
node_engine -->|"compares resources"| node_diff
node_engine -->|"creates sync context"| node_sync
node_sync -->|"applies resources"| node_cluster
node_appset -->|"generates applications"| node_generators
node_appset -->|"creates and updates"| node_appcr
node_appcontroller -.->|"processes hydration"| node_hydrator
node_notifications -->|"observes applications"| node_appcr
node_appsvc -->|"checks project policy"| node_projects
node_server -->|"initializes settings"| node_settings

click node_ui "https://github.com/argoproj/argo-cd/blob/master/ui/src/app/app.tsx"
click node_cli "https://github.com/argoproj/argo-cd/blob/master/cmd/argocd/commands/root.go"
click node_server "https://github.com/argoproj/argo-cd/blob/master/server/server.go"
click node_appsvc "https://github.com/argoproj/argo-cd/blob/master/server/application/application.go"
click node_sessions "https://github.com/argoproj/argo-cd/blob/master/server/session/session.go"
click node_appcr "https://github.com/argoproj/argo-cd/blob/master/pkg/apis/application/v1alpha1/types.go"
click node_reposerver "https://github.com/argoproj/argo-cd/blob/master/reposerver/server.go"
click node_appset "https://github.com/argoproj/argo-cd/blob/master/applicationset/controllers/applicationset_controller.go"
click node_generators "https://github.com/argoproj/argo-cd/blob/master/applicationset/generators/interface.go"
click node_appcontroller "https://github.com/argoproj/argo-cd/blob/master/controller/appcontroller.go"
click node_engine "https://github.com/argoproj/argo-cd/blob/master/gitops-engine/pkg/engine/engine.go"
click node_cache "https://github.com/argoproj/argo-cd/blob/master/gitops-engine/pkg/cache/cluster.go"
click node_diff "https://github.com/argoproj/argo-cd/blob/master/gitops-engine/pkg/diff/diff.go"
click node_sync "https://github.com/argoproj/argo-cd/blob/master/gitops-engine/pkg/sync/sync_context.go"
click node_hydrator "https://github.com/argoproj/argo-cd/blob/master/controller/hydrator/hydrator.go"
click node_notifications "https://github.com/argoproj/argo-cd/blob/master/notification_controller/controller/controller.go"
click node_projects "https://github.com/argoproj/argo-cd/blob/master/server/project/project.go"
click node_settings "https://github.com/argoproj/argo-cd/blob/master/server/settings/settings.go"

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_ui,node_cli toneBlue
class node_server,node_appsvc,node_sessions toneAmber
class node_appcr,node_reposerver,node_appset,node_generators toneMint
class node_appcontroller,node_engine,node_cache,node_diff,node_sync,node_hydrator toneRose
class node_notifications,node_projects,node_settings,node_user,node_repo,node_cluster toneIndigo
```

## Components

### User interaction

- [Web UI](https://github.com/argoproj/argo-cd/blob/master/ui/src/app/app.tsx): `ui/src/app/app.tsx`
- [CLI](https://github.com/argoproj/argo-cd/blob/master/cmd/argocd/commands/root.go): `cmd/argocd/commands/root.go`

### API and services

- [API server](https://github.com/argoproj/argo-cd/blob/master/server/server.go): `server/server.go`
- [Application API](https://github.com/argoproj/argo-cd/blob/master/server/application/application.go): `server/application/application.go`
- [Session service](https://github.com/argoproj/argo-cd/blob/master/server/session/session.go): `server/session/session.go`

### Desired state

- [Application resources](https://github.com/argoproj/argo-cd/blob/master/pkg/apis/application/v1alpha1/types.go): `pkg/apis/application/v1alpha1/types.go`
- [Repo server](https://github.com/argoproj/argo-cd/blob/master/reposerver/server.go): `reposerver/server.go`
- [ApplicationSet controller](https://github.com/argoproj/argo-cd/blob/master/applicationset/controllers/applicationset_controller.go): `applicationset/controllers/applicationset_controller.go`
- [Application generators](https://github.com/argoproj/argo-cd/blob/master/applicationset/generators/interface.go): `applicationset/generators/interface.go`

### Reconciliation

- [Application controller](https://github.com/argoproj/argo-cd/blob/master/controller/appcontroller.go): `controller/appcontroller.go`
- [GitOps engine](https://github.com/argoproj/argo-cd/blob/master/gitops-engine/pkg/engine/engine.go): `gitops-engine/pkg/engine/engine.go`
- [Cluster cache](https://github.com/argoproj/argo-cd/blob/master/gitops-engine/pkg/cache/cluster.go): `gitops-engine/pkg/cache/cluster.go`
- [Resource diff](https://github.com/argoproj/argo-cd/blob/master/gitops-engine/pkg/diff/diff.go): `gitops-engine/pkg/diff/diff.go`
- [Sync executor](https://github.com/argoproj/argo-cd/blob/master/gitops-engine/pkg/sync/sync_context.go): `gitops-engine/pkg/sync/sync_context.go`
- [Manifest hydrator](https://github.com/argoproj/argo-cd/blob/master/controller/hydrator/hydrator.go): `controller/hydrator/hydrator.go`

### Product extensions

- [Notifications](https://github.com/argoproj/argo-cd/blob/master/notification_controller/controller/controller.go): `notification_controller/controller/controller.go`
- [Projects and policy](https://github.com/argoproj/argo-cd/blob/master/server/project/project.go): `server/project/project.go`
- [Settings service](https://github.com/argoproj/argo-cd/blob/master/server/settings/settings.go): `server/settings/settings.go`

### Other components

- **Operator**
- **Git repositories**
- **Kubernetes cluster**

## Connections

- Operator → Web UI: uses
- Operator → CLI: uses
- Web UI → API server: calls API
- CLI → API server: calls API
- API server → Application API: registers service
- API server → Session service: registers service
- Application API → Application resources: reads and writes
- Application resources → Application controller: triggers reconcile
- Application controller → Repo server: requests manifests
- Repo server → Git repositories: reads source
- Application controller → GitOps engine: syncs resources
- GitOps engine → Cluster cache: reads live state
- GitOps engine → Resource diff: compares resources
- GitOps engine → Sync executor: creates sync context
- Sync executor → Kubernetes cluster: applies resources
- ApplicationSet controller → Application generators: generates applications
- ApplicationSet controller → Application resources: creates and updates
- Application controller → Manifest hydrator: processes hydration
- Notifications → Application resources: observes applications
- Application API → Projects and policy: checks project policy
- API server → Settings service: initializes settings
