> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/argoproj/argo-cd/llms.txt
> Use this file to discover all available pages before exploring further.

# Component Architecture

> Understanding Argo CD's component-based architecture for developers

## Design Philosophy

Argo CD is designed with a component-based architecture that provides:

<CardGroup cols={3}>
  <Card title="Modularity" icon="cube">
    Components interact via interfaces, allowing replacement without system-wide changes
  </Card>

  <Card title="Single Responsibility" icon="bullseye">
    Clear boundaries help determine where functionality should be implemented
  </Card>

  <Card title="Reusability" icon="recycle">
    Well-defined interfaces promote service discoverability and reuse
  </Card>
</CardGroup>

## Architecture Overview

```mermaid theme={null}
graph TD
    CLI[CLI] --> API[API Server]
    WebApp[Web App] --> API
    API --> Repo[Repo Server]
    API --> Redis[Redis Cache]
    AppController[Application Controller] --> Repo
    AppController --> K8s[Kubernetes API]
    AppController --> Redis
    AppSetController[ApplicationSet Controller] --> K8s
    Repo --> Git[Git Repository]
    Repo --> Redis
    API --> Dex[Dex OIDC]
```

<Note>
  The default Argo CD installation includes multiple components and Kubernetes controllers. Controllers use proprietary interfaces (CRDs) and lack the modular nature of components.
</Note>

## Logical Layers

Argo CD's architecture is organized into four logical layers with top-down dependencies:

### UI Layer

The presentation layer where users interact with Argo CD.

<CardGroup cols={2}>
  <Card title="Web App" icon="browser">
    Powerful web interface for managing applications deployed in Kubernetes clusters
  </Card>

  <Card title="CLI" icon="terminal">
    Command-line tool for automation, scripting, and interacting with the Argo CD API
  </Card>
</CardGroup>

### Application Layer

Provides capabilities supporting the UI layer.

<Card title="API Server" icon="server">
  Exposes the proprietary API that powers both the Web App and CLI functionality. Handles authentication, authorization, and request routing.
</Card>

### Core Layer

Implements the main GitOps functionality through components and Kubernetes controllers.

<Tabs>
  <Tab title="Application Controller">
    **Responsibilities:**

    * Reconciles Application resources in Kubernetes
    * Synchronizes desired state (from Git) with live state (in Kubernetes)
    * Reconciles Project resources
    * Continuously monitors and maintains application health

    **Type:** StatefulSet
  </Tab>

  <Tab title="ApplicationSet Controller">
    **Responsibilities:**

    * Reconciles ApplicationSet resources
    * Generates Application resources from templates
    * Manages multiple applications across clusters

    **Type:** Deployment
  </Tab>

  <Tab title="Repo Server">
    **Responsibilities:**

    * Interacts with Git repositories
    * Generates desired state for all Kubernetes resources
    * Processes Helm charts, Kustomize, and Jsonnet
    * Supports config management plugins

    **Type:** Deployment

    <Note>
      The Repo Server plays a critical role in Argo CD's architecture as the bridge between source repositories and desired Kubernetes state.
    </Note>
  </Tab>

  <Tab title="Notifications Controller">
    **Responsibilities:**

    * Sends notifications about application events
    * Supports multiple notification channels (Slack, email, etc.)
    * Configurable triggers and templates

    **Type:** Deployment
  </Tab>
</Tabs>

### Infrastructure Layer

Tools that Argo CD depends on for its infrastructure.

<AccordionGroup>
  <Accordion title="Redis" icon="database">
    **Purpose:**

    * Provides caching layer to reduce requests to Kubernetes API and Git providers
    * Supports UI operations
    * Improves performance and responsiveness

    **Type:** Deployment
  </Accordion>

  <Accordion title="Kubernetes API" icon="dharmachakra">
    **Purpose:**

    * Controllers connect to Kubernetes API for the reconciliation loop
    * Stores all Argo CD resources and configuration
    * Target for application deployments

    **Type:** External Dependency
  </Accordion>

  <Accordion title="Git/Helm/OCI Repository" icon="code-branch">
    **Purpose:**

    * Stores desired state of Kubernetes resources
    * Source of truth for GitOps workflows
    * Supports Git repos, Helm repos, and OCI artifact repos

    **Type:** External Dependency
  </Accordion>

  <Accordion title="Dex" icon="shield-halved">
    **Purpose:**

    * Provides authentication with external OIDC providers
    * Enables SSO integration
    * Can be replaced with other OIDC solutions

    **Type:** Deployment (Optional)

    <Tip>
      Check the [user management documentation](https://argo-cd.readthedocs.io/en/latest/operator-manual/user-management/) for alternatives to Dex.
    </Tip>
  </Accordion>
</AccordionGroup>

## Component Dependencies

The diagram shows dependencies between components:

<img src="https://mintlify.s3.us-west-1.amazonaws.com/argoproj-argo-cd-10/assets/argocd-components.png" alt="Component Dependencies" />

**Dependency Rules:**

* Components in upper layers may depend on components in lower layers
* Components in lower layers never depend on components in upper layers
* This maintains clear separation of concerns and prevents circular dependencies

## Development Implications

### Working with the Repo Server

When developing features that involve manifest generation:

<Steps>
  <Step title="Understand the Pipeline">
    Source (Git/Helm/OCI) → Repo Server → Manifests → Application Controller → Kubernetes
  </Step>

  <Step title="Consider Caching">
    Redis caches results to improve performance. Clear cache during development for testing.
  </Step>

  <Step title="Test with Multiple Tools">
    Verify your changes work with Helm, Kustomize, and plain YAML manifests.
  </Step>
</Steps>

### Working with Controllers

When modifying controller behavior:

<Warning>
  **Reconciliation Loop Considerations**

  * Controllers continuously reconcile desired vs. actual state
  * Ensure your changes don't create infinite reconciliation loops
  * Test performance impact with multiple applications
  * Consider rate limiting and back-off strategies
</Warning>

### API Server Development

When adding API endpoints:

```go theme={null}
// Example API server considerations:
// 1. Authentication and authorization checks
// 2. Input validation
// 3. Rate limiting
// 4. Audit logging
// 5. Error handling and user-friendly messages
```

## Port Reference

When running locally or debugging:

| Component                        | API Port | Metrics Port | Debug Port |
| -------------------------------- | -------- | ------------ | ---------- |
| argocd-server                    | 8080     | 8083         | 9345       |
| argocd-repo-server               | 8081     | 8084         | 9346       |
| argocd-redis                     | 6379     | -            | -          |
| argocd-applicationset-controller | -        | 8085         | 9347       |
| argocd-application-controller    | -        | 8086         | 9348       |
| argocd-notifications-controller  | -        | 8087         | 9349       |

<Tip>
  These ports are used by Tilt development setup. See the [Tilt guide](https://argo-cd.readthedocs.io/en/latest/developer-guide/tilt/) for more details.
</Tip>

## Resource Storage

Argo CD stores its state in Kubernetes as Custom Resources:

<Tabs>
  <Tab title="Application">
    ```yaml theme={null}
    apiVersion: argoproj.io/v1alpha1
    kind: Application
    ```

    Represents a deployed application with its source and destination.
  </Tab>

  <Tab title="ApplicationSet">
    ```yaml theme={null}
    apiVersion: argoproj.io/v1alpha1
    kind: ApplicationSet
    ```

    Template for generating multiple Applications.
  </Tab>

  <Tab title="AppProject">
    ```yaml theme={null}
    apiVersion: argoproj.io/v1alpha1
    kind: AppProject
    ```

    Provides logical grouping and access control for Applications.
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Running Locally" icon="laptop-code" href="https://argo-cd.readthedocs.io/en/latest/developer-guide/running-locally/">
    Run Argo CD components locally for development
  </Card>

  <Card title="Debugging" icon="bug" href="https://argo-cd.readthedocs.io/en/latest/developer-guide/debugging-locally/">
    Debug Argo CD components
  </Card>

  <Card title="UI Extensions" icon="puzzle-piece" href="/developers/ui-extensions">
    Extend the Argo CD web interface
  </Card>

  <Card title="Custom Health Checks" icon="heart-pulse" href="/developers/custom-health-checks">
    Add health checks for custom resources
  </Card>
</CardGroup>