# iquantc/github_actions_argocd_gitops architecture

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

- Interactive diagram: https://gitdiagram.com/iquantc/github_actions_argocd_gitops
- Repository: https://github.com/iquantc/github_actions_argocd_gitops

## Overview

##### What this project is (type + purpose)
This repo is a **GitOps CI/CD reference implementation** for a **containerized Node.js app** deployed to **Kubernetes** via **Argo CD**, with **GitHub Actions** building/pushing images and optionally triggering Argo CD sync.

##### Runtime architecture (how traffic reaches the Node app in Kubernetes)
2) **Delivery architecture** (how code changes become a deployed workload: GitHub → Actions → Registry → Argo CD → Kubernetes)

##### Read the file tree as “system components”

- **`app.js`**
The application runtime entrypoint (Node HTTP server; README mentions `/hello` route).
- **`package.json`, `package-lock.json`**
Node dependencies/build metadata (important for the image build stage).
- **`Dockerfile`**
Container build definition (turns Node app into an immutable artifact).
- **`.github/workflows/argo-actions.yml`**
CI pipeline definition (build, push, and Argo CD operations).
- **`manifest/deployment.yaml`**
Kubernetes Deployment (declares Pods, container image tag, replicas, etc).
- **`manifest/service.yaml`**
Kubernetes Service (exposes Deployment internally; README shows port-forwarding; could be NodePort/LoadBalancer depending on edits).

This gives you clear boundaries: **Source → CI → Artifact Registry → GitOps Manifests → CD Controller → Cluster Resources**.

##### Developer / SCM layer
- **Developer workstation**
- **GitHub Repository (this repo)**
- Branch (e.g., `main`) as the “source of truth”
- Contains:
- app source (`app.js`)
- Docker build definition (`Dockerfile`)
- deployment definition (`manifest/*`)
- pipeline definition (`.github/workflows/*`)

- Developer → GitHub: `git push` (code + manifest changes)

##### CI layer (GitHub Actions)
- **GitHub Actions workflow** (`.github/workflows/argo-actions.yml`)
1. Checkout repo
2. Docker build (uses `Dockerfile`, `package*.json`, `app.js`)
3. Docker login (uses `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`)
4. Docker push image to DockerHub
5. (Option A) Update `manifest/deployment.yaml` image tag and commit back (classic GitOps)
6. (Option B) Call `argocd app sync ...` (imperative trigger; still GitOps-ish but less “pure”)

**External dependencies to show**
- **Secrets store: GitHub Actions Secrets**
- `DOCKERHUB_USERNAME`, `DOCKERHUB_TOKEN`
- `ARGOCD_SERVER`, `ARGOCD_USERNAME`, `ARGOCD_PASSWORD`

- GitHub Actions → DockerHub: push image
- GitHub Actions → GitHub Repo: commit manifest update (if implemented)
- GitHub Actions → Argo CD API: `argocd login` and `argocd app sync` (if implemented)

##### Artifact layer (Container Registry)
- **DockerHub repository** (image registry)
- Stores versioned images (tags)
- This is what Kubernetes ultimately pulls

- DockerHub → Kubernetes nodes: image pull (kubelet/container runtime)

##### CD / GitOps layer (Argo CD)
- **Argo CD (running in Kubernetes namespace `argocd`)**
- `argocd-server` (UI/API endpoint you port-forward / NodePort to)
- `argocd-repo-server` (fetches Git repo)
- `argocd-application-controller` (reconciles desired vs live state)
- **Argo CD Application**
- Name (example in README): `argocd-github-actions` / `my-app`
- Watches:
- Repo URL
- Branch/revision: `main`
- Path: `manifest`
- Sync policy: automatic, with prune/self-heal (per README)

- Argo CD → GitHub Repo: pulls manifests from `manifest/`
- Argo CD → Kubernetes API: applies/updates resources (Deployment/Service)

##### Infrastructure / compute layer (as described in README)
The README’s setup is specific and should be drawn explicitly:

- **AWS EC2 Ubuntu instance**
- Runs:
- Docker
- Minikube (Kubernetes cluster)
- kubectl (admin client)
- This EC2 instance is the “host” for the cluster in the tutorial.

- **Minikube Kubernetes Cluster**
- Namespace: `argocd`
- Workloads:
- Argo CD components
- Your app Deployment/Pods
- Your app Service

- User (browser) → EC2 Public IP ports (8080/30007/30008/3000 etc): depends on exposure method
- kubectl (operator) → Kubernetes API: apply/install, port-forward

##### Runtime request path (the “/hello” flow)
Live traffic path clearly:

##### User Browser
2. **Service exposure method** (pick what matches your manifests + README step you want to document)
- Port-forward (common in the README):
- Browser → `PublicIP:8080`
- `kubectl port-forward` tunnels to Service
- Or NodePort (Argo CD UI exposure)
- Or Ingress (optional add-on mentioned)

##### Node.js app (`app.js`) serving `/hello`

- Browser → Service → Pod → Response

##### Relationships & interactions to emphasize (what makes the architecture “GitOps” here)

- **Desired state**: Git repo (`manifest/`)
- **Actual state**: Kubernetes cluster (live resources)
- **Reconciler**: Argo CD (continuously compares and fixes drift if self-heal enabled)

**artifact traceability chain**:
- Commit SHA / version → Image tag → Deployment image reference → Running Pod

- Developer
- GitHub
- GitHub Actions
- DockerHub
- Argo CD
- Kubernetes (Minikube on EC2)
- End user/browser

- Developer
- GitHub
- GitHub Actions
- DockerHub
- Argo CD
- Kubernetes API

Steps:
- commit
- workflow triggers
- build image
- push image
- update manifest (or not)
- Argo pulls repo
- Argo applies manifests
- cluster pulls image
- rollout

Inside “Minikube cluster”:
- Namespace `argocd`:
- Argo CD components (server/controller/repo-server)
- Your app Deployment → ReplicaSet → Pods
- Your app Service
- Exposure:
- port-forward / NodePort / Ingress (choose what you actually used)

##### Concrete labeling guidance (tie labels to repo files + README)

- “GitHub Actions Workflow: `.github/workflows/argo-actions.yml`”
- “K8s Deployment: `manifest/deployment.yaml` (image: `<dockerhub>/<repo>:<tag>` )”
- “K8s Service: `manifest/service.yaml` (ports …)”
- “Node app endpoint: `/hello` from `app.js`”
- “Argo CD App path: `manifest/`, revision: `main`”
- “Secrets: DOCKERHUB_*, ARGOCD_* (GitHub Actions Secrets)”

##### “Separate into as many components as possible” (without overthinking)
- GitHub Actions Runner (ephemeral runner VM)
- GitHub Actions Secrets (distinct node)
- Argo CD server vs controller vs repo-server
- Kubernetes API Server (even in Minikube)
- NodePort/port-forward tunnel as a first-class component
- Namespace boundaries (`argocd`)
- Security group / inbound ports on EC2 (since README relies on opening ports)

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% Diagram 1: System Context (Runtime + Delivery)
  %% =========================

  EndUser["End User / Browser"]:::external
  Dev["Developer Workstation"]:::external

  GitHubRepo[("GitHub Repository (source of truth)\n- app source\n- Docker build\n- GitOps manifests\n- CI workflow")]:::store
  ReadmeFile["README.md"]:::store
  GitOpsManifests[("manifest/ (GitOps desired state)")]:::store

  subgraph CI["CI Layer (GitHub)"]
    GHA["GitHub Actions Workflow\n(build/login/push + Argo ops)"]:::automation
    GHARunner["GitHub Actions Runner (ephemeral)"]:::compute
    GHASecrets[("GitHub Actions Secrets\nDOCKERHUB_* / ARGOCD_*")]:::store
    GHA -->|"runs_on"| GHARunner
    GHASecrets -.->|"injects_env"| GHA
  end

  DockerHub[("DockerHub Container Registry\n(versioned image tags)")]:::store
  DockerfileNode["Dockerfile"]:::store
  PackageJsonNode["package.json"]:::store
  PackageLockNode["package-lock.json"]:::store

  subgraph Infra1["Infrastructure: AWS EC2 Ubuntu Host"]
    EC2["EC2 Instance (Ubuntu)\nDocker + Minikube + kubectl"]:::compute

    subgraph MK1["Minikube Kubernetes Cluster"]
      KubeAPI["Kubernetes API Server"]:::automation

      subgraph NSArgo1["Namespace: argocd"]
        ArgoServer["argocd-server (UI/API)"]:::automation
        ArgoRepo["argocd-repo-server (fetch Git)"]:::automation
        ArgoController["argocd-application-controller\n(reconcile desired vs live)"]:::automation
        ArgoApp["Argo CD Application\n(revision: main, path: manifest,\nauto-sync + prune + self-heal)"]:::automation
      end

      subgraph AppWorkloads1["Application Workloads"]
        K8sService["Kubernetes Service\n(exposes app in-cluster)"]:::compute
        K8sDeploy["Kubernetes Deployment\n(Pods/replicas + image ref)"]:::compute
        Pods["App Pods (ReplicaSet-managed)"]:::compute
        NodeApp["Node.js App\nHTTP GET /hello"]:::compute

        K8sDeploy -->|"creates"| Pods
        Pods -->|"runs"| NodeApp
        K8sService -->|"routes_to"| Pods
      end
    end
  end

  %% Repo contents (for navigation)
  GitHubRepo -->|"contains"| ReadmeFile
  GitHubRepo -->|"contains"| GitOpsManifests
  GitHubRepo -->|"contains"| DockerfileNode
  GitHubRepo -->|"contains"| PackageJsonNode
  GitHubRepo -->|"contains"| PackageLockNode

  %% Delivery flow (control-plane)
  Dev -->|"git_push"| GitHubRepo
  GitHubRepo -->|"workflow_trigger"| GHA
  GHA -->|"docker_build"| DockerHub
  GHA -->|"docker_push"| DockerHub

  %% GitOps desired-state + reconciliation loop
  ArgoRepo -.->|"pull_manifests (manifest/)"| GitOpsManifests
  ArgoController -.->|"reconcile_desired_vs_live"| ArgoApp
  ArgoApp -.->|"apply_Deployment/Service"| KubeAPI
  KubeAPI -.->|"creates/updates"| K8sDeploy
  KubeAPI -.->|"creates/updates"| K8sService

  %% Optional imperative trigger from CI
  GHA -.->|"argocd_login + app_sync"| ArgoServer

  %% Artifact pull into runtime
  DockerHub -->|"image_pull"| Pods

  %% Runtime traffic (data-plane)
  PortForward["kubectl port-forward tunnel\n(PublicIP:8080 -> Service)"]:::automation
  EndUser -->|"HTTP_GET_/hello"| PortForward
  PortForward -->|"forwards_to"| K8sService
  K8sService -->|"HTTP"| Pods

  %% =========================
  %% Diagram 2: CI/CD Pipeline (Sequence as Flow)
  %% =========================
  subgraph Seq["CI/CD Pipeline (Sequence View)"]
    direction TB
    SD_D["Developer"]:::external
    SD_R["GitHub Repo (main)"]:::store
    SD_A["GitHub Actions Workflow"]:::automation
    SD_S["Actions Secrets"]:::store
    SD_H["DockerHub Registry"]:::store
    SD_AS["Argo CD Server (API)"]:::automation
    SD_AR["Argo CD Repo-Server"]:::automation
    SD_AC["Argo CD App-Controller"]:::automation
    SD_K["Kubernetes API"]:::automation
    SD_P["App Pods"]:::compute

    SD_D -->|"git push (code + manifests)"| SD_R
    SD_R -->|"workflow trigger (on push)"| SD_A
    SD_S -.->|"provide DOCKERHUB_* and ARGOCD_* secrets"| SD_A
    SD_A -->|"checkout repository"| SD_R
    SD_A -->|"docker build (Dockerfile + package*.json + app.js)"| SD_A
    SD_A -->|"docker login"| SD_H
    SD_A -->|"docker push (image:tag)"| SD_H

    SD_A -->|"Option A: update manifest/deployment.yaml image tag\ncommit + push (manifests)"| SD_R
    SD_A -.->|"Option B: argocd login\nargocd app sync <app>"| SD_AS

    SD_AR -.->|"pull manifests (path: manifest/, rev: main)"| SD_R
    SD_AC -.->|"apply/patch Deployment + Service"| SD_K
    SD_K -->|"rollout (create/update Pods)"| SD_P
    SD_P -.->|"pull image (by tag)"| SD_H
    SD_P -->|"start Node.js server (/hello)"| SD_P
  end

  %% =========================
  %% Diagram 3: Kubernetes Deployment View (Minikube on EC2)
  %% =========================
  subgraph DepView["Kubernetes Deployment View (Minikube on EC2)"]
    direction TB

    subgraph EC2Box["AWS EC2 Ubuntu Instance"]
      EC2Host["EC2 Host\n(Docker + Minikube + kubectl)"]:::compute

      subgraph MK3["Minikube Cluster"]
        K8sAPI3["Kubernetes API Server"]:::automation

        subgraph NSArgo3["Namespace: argocd"]
          ArgoServer3["argocd-server\n(UI/API; NodePort/port-forward)"]:::automation
          ArgoRepo3["argocd-repo-server\n(fetch Git repo)"]:::automation
          ArgoController3["argocd-application-controller\n(self-heal + prune)"]:::automation
          ArgoApp3["Argo CD Application\n(path: manifest/, rev: main)"]:::automation
        end

        subgraph NSDefault3["Namespace: default (app)"]
          Svc3["Service (manifest/service.yaml)"]:::compute
          Deploy3["Deployment (manifest/deployment.yaml)\nimage: <dockerhub>/<repo>:<tag>"]:::compute
          RS3["ReplicaSet"]:::compute
          Pod3["Pod(s)"]:::compute
          App3["Node.js container\n(app.js) serving /hello"]:::compute
        end

        Deploy3 -->|"creates"| RS3
        RS3 -->|"creates"| Pod3
        Pod3 -->|"runs"| App3
        Svc3 -->|"selects"| Pod3

        GitRepo3[("GitHub Repo\n(manifest/)")]:::store
        ArgoRepo3 -.->|"pulls_desired_state"| GitRepo3
        ArgoController3 -.->|"reconciles"| ArgoApp3
        ArgoApp3 -.->|"apply"| K8sAPI3
        K8sAPI3 -.->|"creates/updates"| Deploy3
        K8sAPI3 -.->|"creates/updates"| Svc3
      end

      Kubectl3["kubectl (operator/admin)"]:::automation
      Kubectl3 -.->|"apply/install/port-forward"| K8sAPI3
      PortFwd3["port-forward\nPublicIP:8080 -> Service"]:::automation
      Kubectl3 -.->|"creates_tunnel"| PortFwd3
    end

    Browser3["Browser"]:::external
    Browser3 -->|"HTTP_GET_/hello"| PortFwd3
    PortFwd3 -->|"to_Service"| Svc3
    Svc3 -->|"to_Pods"| Pod3

    Readme3["README.md"]:::store
    GitRepo3 -->|"docs"| Readme3
  end

  %% Click events (mapped components)
  click NodeApp "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/app.js"
  click ReadmeFile "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/README.md"
  click GHA "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/.github/workflows/argo-actions.yml"
  click K8sDeploy "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/manifest/deployment.yaml"
  click K8sService "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/manifest/service.yaml"
  click DockerfileNode "https://github.com/iquantc/github_actions_argocd_gitops/tree/main/Dockerfile"
  click GitOpsManifests "https://github.com/iquantc/github_actions_argocd_gitops/tree/main/manifest/"
  click PackageJsonNode "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/package.json"
  click PackageLockNode "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/package-lock.json"

  click App3 "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/app.js"
  click Deploy3 "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/manifest/deployment.yaml"
  click Svc3 "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/manifest/service.yaml"
  click GitRepo3 "https://github.com/iquantc/github_actions_argocd_gitops/tree/main/manifest/"
  click Readme3 "https://github.com/iquantc/github_actions_argocd_gitops/blob/main/README.md"

  %% Styles
  classDef external fill:#f3f4f6,stroke:#374151,color:#111827,stroke-width:1px
  classDef store fill:#e5e7eb,stroke:#374151,color:#111827,stroke-width:1px
  classDef automation fill:#ffedd5,stroke:#9a3412,color:#7c2d12,stroke-width:1px
  classDef compute fill:#dbeafe,stroke:#1e40af,color:#1e3a8a,stroke-width:1px
```
