# dag-andersen/argocd-diff-preview architecture

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

- Interactive diagram: https://gitdiagram.com/dag-andersen/argocd-diff-preview
- Repository: https://github.com/dag-andersen/argocd-diff-preview

## Overview

##### Project type and purpose
- This is an open-source CLI tool (written in Go) packaged as a Docker image.
- Purpose: spin up an ephemeral Kubernetes cluster, install Argo CD, render manifests from two Git branches (base vs. target), compute a diff, and output it (e.g., as Markdown).
- It integrates with GitHub Actions (or any CI) to comment diffs on PRs, much like Terraform’s Atlantis.

##### File structure
- Top-level:
- cmd/       → CLI entry point (main.go, options.go)
- pkg/       → core libraries broken out by concern (argocd, k8s, diff, git, cluster provisioning, utils)
- Dockerfile → packages CLI into a container that mounts Docker socket and host folders
- argocd-config/ → Argo CD Helm values for overriding defaults
- examples/, docs/ → usage demos, tutorials, and a MkDocs-driven site
- .github/workflows/ → GitHub Actions pipelines (generate-diff, release Docker/binary, MkDocs)
- tests/     → integration test fixtures and Kind/Minikube configs
- Patterns:
- Modular Go packages (single responsibility in pkg/)
- CLI-on-Docker pattern (containerized tooling)
- Ephemeral-infrastructure provisioning (k3d/kind/minikube)
- GitOps flow via Argo CD in a throwaway cluster

##### README for additional insights
- Supported features: private repos, Helm charts, Kustomize overlays, multi-source Applications.
- CI integration: mounts base/target branches and Docker socket, sets env vars (TARGET_BRANCH, REPO), runs container.

a. Main components
1. Developer/CI trigger
2. Docker container (argocd-diff-preview image)
3. Docker daemon (host socket)
4. Ephemeral Kubernetes cluster (Kind/K3d/Minikube)
5. Argo CD control plane inside cluster
6. Git repositories (base-branch, target-branch)
7. Manifest extraction & diff engine (Go modules in pkg/)
8. Output sink (volume mount → output/diff.md)
9. GitHub API (optional: posting PR comment)
b. Relationships & interactions
- CI or user invokes the Docker container.
- Container talks to host Docker daemon (via mounted socket) to provision a cluster.
- Once cluster is up, container deploys Argo CD using Helm values from argocd-config/.
- Container points Argo CD at base and target branches as two Applications (or ApplicationSets).
- Argo CD syncs and renders manifests into the cluster’s discardable namespace.
- Container’s Go code calls into pkg/argoapplication and pkg/k8s to fetch live manifests from Argo CD.
- pkg/diff computes the delta, formats Markdown.
- diff.md is written to a host-mounted /output directory.
- (In GitHub Actions) a final step uses GitHub CLI to post the diff.md as a PR comment.
c. Architectural patterns / design principles
- Single-responsibility modules in pkg/ (e.g., pkg/diff, pkg/git, pkg/k8s).
- Dependency inversion: CLI code (cmd/) orchestrates high-level flow using pkg/.
- Side-effect isolation: all work happens in a throwaway cluster/container; no real cluster or Argo CD access needed.
- Declarative infra: cluster provisioning via code (k3d/kind), Argo CD install via Helm.
d. Technologies / frameworks
- Go modules / Go CLI
- Docker (for container) & host Docker socket
- Kind / k3d / Minikube (cluster provisioning)
- Helm (Argo CD install, argocd-config values)
- Argo CD API / CLI libraries (pkg/argocd)
- GitHub Actions & GitHub CLI (CI integration)
- MkDocs (documentation site)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI Layer
    subgraph "CI Orchestrator"
        CI["GitHub Actions\n(.github/workflows/generate-diff.yml)"]:::ci
    end

    %% Host Environment
    subgraph "Host Environment"
        DockerDaemon["Docker Daemon\n(host socket)"]:::infra
        RepoBase["Git Repo: Base Branch"]:::data
        RepoTarget["Git Repo: Target Branch"]:::data
        OutputVol["Output Volume\n(/output/diff.md)"]:::data
        GitHubAPI["GitHub API\n(post PR comment)"]:::infra
    end

    %% Docker Container Boundary
    subgraph "Docker Container\n(argocd-diff-preview image)" 
        direction TB
        CLI["CLI Orchestrator\ncmd/main.go\ncmd/options.go"]:::code
        Provisioners["Cluster Provisioners"]:::code
        subgraph "Provisioners"
            direction TB
            KindProv["Kind Provisioner\npkg/kind/kind.go"]:::code
            K3dProv["k3d Provisioner\npkg/k3d/k3d.go"]:::code
            MinikubeProv["Minikube Prov.\npkg/minikube/minikube.go"]:::code
        end
        ArgoInstaller["Argo CD Installer\npkg/argocd/argocd.go"]:::code
        ArgoUtils["Argo CD Utils\npkg/argocd/utils.go"]:::code
        AppConv["App Conversion\npkg/argoapplication/applications.go"]:::code
        AppFilter["App Filter\npkg/argoapplication/filter.go"]:::code
        AppConvert["App Conversion Utils\npkg/argoapplication/conversion.go"]:::code
        Extractor["Manifest Extractor\npkg/extract/extract.go"]:::code
        K8sParser["K8s Parser\npkg/k8s/parser.go"]:::code
        K8sResource["K8s Resource\npkg/k8s/resource.go"]:::code
        GitOps["Git Operations\npkg/git/branch.go"]:::code
        DiffEngine["Diff Engine\npkg/diff/diff.go"]:::code
        DiffFormat["Diff Format\npkg/diff/format.go"]:::code
        MDFormat["Markdown Format\npkg/diff/markdown.go"]:::code
        UtilsKS["K8s Client Utils\npkg/utils/k8s-client.go"]:::util
        UtilsGen["General Utils\npkg/utils/utils.go"]:::util
        Selector["Selector Logic\npkg/selector/selector.go"]:::code
        ArgoConfig["Argo CD Helm Values\nargocd-config/values.yaml\nargocd-config/values-override.yaml"]:::infra
    end

    %% Ephemeral Cluster
    subgraph "Ephemeral K8s Cluster"
        ArgoCD["Argo CD Control Plane"]:::app
    end

    %% Documentation & Examples
    Docs["MkDocs Site\ndocs/ & mkdocs.yml"]:::infra
    Examples["Example Scenarios\nexamples/"]:::infra
    Tests["Integration Tests\ntests/"]:::infra

    %% Connections
    CI -->|invokes| CLI
    CLI -->|uses| DockerDaemon
    CLI -->|mounts| RepoBase
    CLI -->|mounts| RepoTarget
    CLI -->|reads| ArgoConfig
    CLI -->|calls| GitOps

    CLI -->|provisions| KindProv
    CLI -->|provisions| K3dProv
    CLI -->|provisions| MinikubeProv
    KindProv -->|creates| ArgoCD
    K3dProv -->|creates| ArgoCD
    MinikubeProv -->|creates| ArgoCD

    CLI -->|installs| ArgoInstaller
    ArgoInstaller -->|uses| ArgoUtils
    ArgoInstaller -->|deploys| ArgoCD

    CLI -->|converts apps| AppConv
    CLI -->|filters apps| AppFilter
    CLI -->|converts meta| AppConvert

    AppConv -->|syncs| ArgoCD
    AppFilter -->|syncs| ArgoCD

    CLI -->|extracts| Extractor
    Extractor -->|parses| K8sParser
    Extractor -->|parses| K8sResource
    Extractor -->|fetches| ArgoCD

    CLI -->|diffs| DiffEngine
    DiffEngine -->|formats| DiffFormat
    DiffFormat -->|marksdown| MDFormat
    MDFormat -->|writes| OutputVol

    CLI -->|uses| UtilsKS
    CLI -->|uses| UtilsGen
    CLI -->|uses| Selector

    OutputVol -->|consumed by| GitHubAPI
    GitHubAPI -->|comments on| CI

    CI -->|publishes| Docs
    CI -->|publishes| Examples
    CI -->|runs tests in| Tests

    %% Click Events
    click CI "https://github.com/dag-andersen/argocd-diff-preview/blob/main/.github/workflows/generate-diff.yml"
    click DockerDaemon "https://github.com/dag-andersen/argocd-diff-preview/tree/main/Dockerfile"
    click ArgoConfig "https://github.com/dag-andersen/argocd-diff-preview/blob/main/argocd-config/values.yaml"
    click ArgoConfig "https://github.com/dag-andersen/argocd-diff-preview/blob/main/argocd-config/values-override.yaml"
    click CLI "https://github.com/dag-andersen/argocd-diff-preview/blob/main/cmd/main.go"
    click CLI "https://github.com/dag-andersen/argocd-diff-preview/blob/main/cmd/options.go"
    click KindProv "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/kind/kind.go"
    click K3dProv "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/k3d/k3d.go"
    click MinikubeProv "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/minikube/minikube.go"
    click ArgoInstaller "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/argocd/argocd.go"
    click ArgoUtils "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/argocd/utils.go"
    click AppConv "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/argoapplication/applications.go"
    click AppFilter "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/argoapplication/filter.go"
    click AppConvert "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/argoapplication/conversion.go"
    click Extractor "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/extract/extract.go"
    click K8sParser "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/k8s/parser.go"
    click K8sResource "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/k8s/resource.go"
    click GitOps "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/git/branch.go"
    click DiffEngine "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/diff/diff.go"
    click DiffFormat "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/diff/format.go"
    click MDFormat "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/diff/markdown.go"
    click UtilsKS "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/utils/k8s-client.go"
    click UtilsGen "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/utils/utils.go"
    click Selector "https://github.com/dag-andersen/argocd-diff-preview/blob/main/pkg/selector/selector.go"
    click Tests "https://github.com/dag-andersen/argocd-diff-preview/tree/main/tests/"
    click Docs "https://github.com/dag-andersen/argocd-diff-preview/tree/main/docs/"
    click Examples "https://github.com/dag-andersen/argocd-diff-preview/tree/main/examples/"

    %% Styles
    classDef infra fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef app fill:#caffbf,stroke:#333,stroke-width:1px
    classDef data fill:#ffd6a5,stroke:#333,stroke-width:1px
    classDef ci fill:#d3d3d3,stroke:#333,stroke-width:1px
    classDef code fill:#bdb2ff,stroke:#333,stroke-width:1px
    classDef util fill:#fffffc,stroke:#333,stroke-width:1px
```
