# argoproj/gitops-engine architecture

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

- Interactive diagram: https://gitdiagram.com/argoproj/gitops-engine
- Repository: https://github.com/argoproj/gitops-engine

## Overview

##### Project type and purpose
- This is a Go-based, reusable GitOps library + example “agent” CLI.
- Core purpose: provide Kubernetes resource caching, diffing, sync planning, manifest generation, health assessment, and reconciliation logic.

##### File structure
- Top-level “agent” folder: standalone CLI that consumes the engine to deploy itself into clusters via Kustomize manifests.
- “pkg/engine”: entry point to the core library.
- “pkg/cache”, “pkg/diff”, “pkg/sync”, “pkg/health”, “pkg/utils”: modular subpackages realizing specific GitOps functions.
- “internal/kubernetes_vendor”: vendored Kubernetes client code.
- “specs” and “docs”: design proposals and usage guidance (not part of runtime path).

##### README
- Confirms core features: cache, reconciliation, sync planning, Git access, manifest generation.
- Points to design spec in specs/design.md for deeper architecture rationale.

##### Decompose into main components
a. Consumer layer
- Agent CLI (agent/main.go + Kustomize manifests)
b. Engine core
- Engine façade (pkg/engine)
- Cache manager (pkg/cache)
- Diff engine (pkg/diff + internal/fieldmanager)
- Sync planner & executor (pkg/sync)
- Health evaluator (pkg/health)
- Utility modules (pkg/utils for I/O, JSON, kube client, tracing, testing)
c. External systems
- Git server(s) (GitOps repo)
- Kubernetes API server(s)
- Optional plugin/hook tools (e.g., Helm hooks under pkg/sync/hook/helm)

##### Relationships and data flow
- Agent CLI invokes Engine façade →
- Reads desired manifests from Git → engine uses utils/kube + utils/io to fetch and parse →
- Cache layer loads live cluster state from K8s API →
- Diff engine computes desired vs. live →
- Sync planner builds reconciliation plan (pkg/sync → hook orchestration) →
- Sync executor applies resources to K8s →
- Health evaluator monitors resource health →
- Engine returns status back to CLI/user or higher-level orchestrator.
- All components communicate via well-defined Go interfaces and share the same process.

##### Architectural patterns
- Layered modular design (separation of cache, diff, sync, health, utils).
- Pluggable hooks (strategy pattern under pkg/sync/hook).
- Use of mocks for testing (pkg/*/mocks) demonstrates dependency-inversion for unit tests.
- Externalization of K8s vendor code under internal/ for API compatibility.

##### Technologies and frameworks
- Go modules, Go interfaces
- Kubernetes client-go (vendored)
- Kustomize for agent deployment
- Standard Git protocols (SSH/HTTPS) via Go-git or native exec
- CI/CD workflows (GitHub Actions via .github/workflows/ci.yaml)
- Dockerfile for containerized agent

##### Detail
- Module names exactly as in the file tree for clarity.
- Interfaces (e.g., SyncContext, ClusterCache, DiffRunner).
- That all modules live in-process and interconnect via Go calls, not via network calls.
- Optional flows (e.g., fieldmanager under diff/internal).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Consumer Layer"
        AgentCLI["Agent CLI"]:::consumer
        Manifests["manifests (Kustomize)"]:::consumer
    end

    subgraph "GitOps Engine"
        subgraph "Engine Façade"
            EngineCore["engine.go"]:::core
            EngineOpts["engine_options.go"]:::core
        end
        CacheManager["pkg/cache"]:::core
        DiffEngine["pkg/diff"]:::core
        FieldManager["fieldmanager (pkg/diff/internal)"]:::core
        SyncPlanner["pkg/sync"]:::core
        HealthEvaluator["pkg/health"]:::core
        Utils["pkg/utils"]:::core
        KubeVendor["internal/kubernetes_vendor"]:::core
    end

    AgentCLI --> EngineCore
    Manifests --> EngineCore
    EngineCore -->|"git clone/fetch"| GitServer
    EngineCore -->|"GET /resources"| K8sAPI
    EngineCore -->|"load cache"| CacheManager
    EngineCore -->|"compute diff"| DiffEngine
    DiffEngine -->|"use FM"| FieldManager
    EngineCore -->|"plan sync"| SyncPlanner
    EngineCore -->|"assess health"| HealthEvaluator
    EngineCore -->|"util funcs"| Utils
    EngineCore -->|"vendor k8s client"| KubeVendor

    GitServer["Git Server"]:::external
    K8sAPI["Kubernetes API Server"]:::external

    classDef consumer fill:#D6EAF8,stroke:#000
    classDef core fill:#D5F5E3,stroke:#000
    classDef external fill:#FCF3CF,stroke:#000

    click AgentCLI "https://github.com/argoproj/gitops-engine/blob/master/agent/main.go"
    click Manifests "https://github.com/argoproj/gitops-engine/tree/master/agent/manifests/"
    click EngineCore "https://github.com/argoproj/gitops-engine/blob/master/pkg/engine/engine.go"
    click EngineOpts "https://github.com/argoproj/gitops-engine/blob/master/pkg/engine/engine_options.go"
    click CacheManager "https://github.com/argoproj/gitops-engine/tree/master/pkg/cache/"
    click DiffEngine "https://github.com/argoproj/gitops-engine/tree/master/pkg/diff/"
    click FieldManager "https://github.com/argoproj/gitops-engine/tree/master/pkg/diff/internal/fieldmanager/"
    click SyncPlanner "https://github.com/argoproj/gitops-engine/tree/master/pkg/sync/"
    click HealthEvaluator "https://github.com/argoproj/gitops-engine/tree/master/pkg/health/"
    click Utils "https://github.com/argoproj/gitops-engine/tree/master/pkg/utils/"
    click KubeVendor "https://github.com/argoproj/gitops-engine/tree/master/internal/kubernetes_vendor/"
```
