# argoproj/argo-workflows architecture

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

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

## Overview

##### Main Components
- Client Interfaces: Represent the various client entry points such as the Argo CLI, REST/GRPC API endpoints, and the Web UI (located under the “ui” directory). These components allow users to submit, monitor, and manage workflows.
- Workflow Controller: The core component (in the “cmd/workflow-controller” and “server/workflow” directories) that watches Kubernetes CRDs and orchestrates workflow execution by coordinating with executors, managing retries, suspension, and termination.
- API Server and Supporting Services: Under “server/apiserver” and “server/info”, these serve user requests and provide endpoints for configuration, logging, and access control. Also include the authentication modules (in “server/auth”) that cover service account verification, SSO, webhooks, and gatekeeper integrations.
- Workflow Executors: The executors (in “cmd/argoexec” and related “server/artifacts”, “server/executor”) are pieces that launch container tasks in pods based on the workflow specification.
- Artifact Management and Persistence: Represent how workflows archive results (see the “workflowarchive” and “persist/sqldb” folders) and handle artifacts (with support for multiple backends like S3, GCS, Git, etc).
- Event Sources & Sensors: Capture the event-driven aspects (present in “server/event”, “server/eventsource” and in client libraries) that trigger workflows or integrate with external event-driven systems.
- Client Libraries: Although not explicitly services, note that the SDKs (in sdks/) for Java, Golang, and Python enable external systems to interact with Argo programmatically.

##### Relationships and Data Flow
- That the API Server communicates with the Kubernetes API and then the Workflow Controller picks up new/updated workflow CRDs.
- Authentication and authorization flow – for example, the API Server calls the authentication modules (SSO via webhooks or serviceaccounts) before processing requests.
- External integrations such as event triggers (e.g., webhooks, sensors) that feed events into the system and cause workflows to start.

##### Design Patterns and Technologies
- Use a microservices or modular architecture style. Different servers (API server, workflow controller, executor, artifact server) should be shown as distinct yet interconnected modules.
- That the system leverages Kubernetes CRDs for orchestration and uses the Kubernetes API for storing its state (backed by etcd).
- Technologies: container orchestration (Kubernetes), REST/GRPC APIs, CI/CD integration, and the various client libraries.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client Layers
    subgraph "Client Interfaces"
        CLI["CLI"]
        UI["Web UI"]
    end

    subgraph "Client Libraries"
        SDKs["SDKs"]
    end

    %% API Server and Supporting Services
    subgraph "API Server & Supporting Services"
        APIServer["API Server"]
        Info["Information Endpoints"]
        Auth["Authentication"]
    end

    %% Kubernetes API and Custom Resources
    K8s["Kubernetes API (etcd)"]
    
    subgraph "Custom Resources"
        CRD["CRD definitions"]
    end

    %% Workflow Controller
    subgraph "Workflow Controller"
        ControllerExec["Controller executable"]
        WorkflowServer["Workflow server logic"]
    end

    %% Executors and Artifact Management
    subgraph "Workflow Executors & Artifacts"
        Executor["Executor command"]
        Artifact["Artifact server"]
        Persistence["Persistence layer"]
    end

    %% Event Sources & Sensors
    subgraph "Event Sources & Sensors"
        EventService["Event handling"]
        EventSource["Eventsource"]
        Sensor["Sensor service"]
    end

    %% Connections from Client Layers to API Server
    CLI -->|"submit_workflow"| APIServer
    UI  -->|"submit_workflow"| APIServer
    SDKs -->|"API_call"| APIServer

    %% API Server interactions
    APIServer -->|"validate"| Auth
    APIServer -->|"fetch_info"| Info
    APIServer -->|"k8s_request"| K8s

    %% Kubernetes API and CRD flow
    K8s -->|"store_CRDs"| CRD
    CRD -->|"watch_CRD"| WorkflowServer

    %% API Server to Workflow Controller
    APIServer -->|"start_workflow"| WorkflowServer

    %% Workflow Controller interactions
    WorkflowServer -->|"dispatch_task"| Executor
    WorkflowServer -->|"archive_result"| Artifact

    %% Artifact Management
    Artifact -->|"store_artifact"| Persistence

    %% Event Sources and Sensors trigger workflows
    EventService -->|"trigger_workflow"| WorkflowServer
    EventSource -->|"trigger_workflow"| WorkflowServer
    Sensor -->|"trigger_workflow"| WorkflowServer

    %% Styling Classes
    class CLI,UI client;
    class SDKs sdk;
    class APIServer,Info,Auth api;
    class K8s k8s;
    class CRD crd;
    class ControllerExec,WorkflowServer controller;
    class Executor executor;
    class Artifact,Persistence artifact;
    class EventService,EventSource,Sensor event;

    %% Class Definitions
    classDef client fill:#add8e6,stroke:#000,stroke-width:1px;
    classDef sdk fill:#ffcccb,stroke:#000,stroke-width:1px;
    classDef api fill:#90ee90,stroke:#000,stroke-width:1px;
    classDef k8s fill:#e0ffff,stroke:#000,stroke-width:1px;
    classDef crd fill:#d3d3d3,stroke:#000,stroke-width:1px;
    classDef controller fill:#ffdead,stroke:#000,stroke-width:1px;
    classDef executor fill:#dda0dd,stroke:#000,stroke-width:1px;
    classDef artifact fill:#e6e6fa,stroke:#000,stroke-width:1px;
    classDef event fill:#ffff99,stroke:#000,stroke-width:1px;

    %% Click Events
    click CLI "https://github.com/argoproj/argo-workflows/tree/main/cmd/argo"
    click UI "https://github.com/argoproj/argo-workflows/tree/main/ui"
    click SDKs "https://github.com/argoproj/argo-workflows/tree/main/sdks"
    click APIServer "https://github.com/argoproj/argo-workflows/tree/main/server/apiserver"
    click Info "https://github.com/argoproj/argo-workflows/tree/main/server/info"
    click Auth "https://github.com/argoproj/argo-workflows/tree/main/server/auth"
    click ControllerExec "https://github.com/argoproj/argo-workflows/tree/main/cmd/workflow-controller"
    click WorkflowServer "https://github.com/argoproj/argo-workflows/tree/main/server/workflow"
    click Executor "https://github.com/argoproj/argo-workflows/tree/main/cmd/argoexec"
    click Artifact "https://github.com/argoproj/argo-workflows/tree/main/server/artifacts"
    click Persistence "https://github.com/argoproj/argo-workflows/tree/main/persist/sqldb"
    click EventService "https://github.com/argoproj/argo-workflows/tree/main/server/event"
    click EventSource "https://github.com/argoproj/argo-workflows/tree/main/server/eventsource"
    click Sensor "https://github.com/argoproj/argo-workflows/tree/main/server/sensor"
    click CRD "https://github.com/argoproj/argo-workflows/tree/main/manifests/base/crds"
```
