Argo CD - Declarative GitOps Continuous Delivery for Kubernetes

Overview

Argo CD is a declarative, GitOps continuous delivery tool for Kubernetes. It enables you to define your application state in Git repositories and automatically synchronize your Kubernetes clusters to match that desired state.

What is Argo CD?

Argo CD implements the GitOps philosophy: your Git repository becomes the single source of truth for your infrastructure and applications. Instead of manually applying changes to clusters, Argo CD continuously monitors your Git repositories and automatically deploys changes when they're detected. This approach provides auditability, version control, and automated rollback capabilities.

Core Principles

Argo CD is built on two fundamental principles:

1. Declarative Configuration - Application definitions, configurations, and environments are version-controlled in Git repositories
2. Automated Deployment - Application deployment and lifecycle management are automated, auditable, and easy to understand

Key Concepts

Understanding these core concepts is essential for working with Argo CD:

• Application - A group of Kubernetes resources defined by a manifest (Custom Resource Definition)
• Target State - The desired state of an application as represented by files in a Git repository
• Live State - The actual state of deployed resources in your Kubernetes cluster
• Sync Status - Whether the live state matches the target state
• Sync - The process of making an application move to its target state
• Health - Whether the application is running correctly and can serve requests
• Tool - A configuration management tool like Kustomize, Helm, or Jsonnet used to generate manifests

System Architecture

Loading diagram...

Core Components

API Server - Exposes gRPC/REST APIs consumed by the Web UI, CLI, and CI/CD systems. Handles application management, authentication, RBAC, and webhook processing.

Repository Server - Maintains a local cache of Git repositories and generates Kubernetes manifests based on repository content, revision, and configuration management tool settings.

Application Controller - A Kubernetes controller that continuously monitors applications and compares live state against target state. Detects drift and optionally takes corrective action.

Getting Started

To begin using Argo CD, you need:

• A Kubernetes cluster with kubectl configured
• Git repository containing your application manifests
• Basic understanding of Kubernetes, Docker, and your chosen templating tool (Kustomize, Helm, etc.)

The typical workflow involves creating an Application resource that points to your Git repository, and Argo CD handles the rest—continuously syncing your cluster to match your Git state.

Architecture & Core Components

Argo CD follows a component-based, layered architecture designed for modularity, single responsibility, and reusability. The system is organized into four logical layers: UI, Application, Core, and Infrastructure.

Core Components

API Server (server/server.go) - A gRPC/REST server exposing the primary API consumed by the Web UI, CLI, and CI/CD systems. Responsibilities include application management, operation invocation (sync, rollback), credential management, authentication/RBAC enforcement, and Git webhook processing. The server multiplexes gRPC and HTTP traffic using cmux and includes comprehensive interceptors for logging, metrics, and error handling.

Repository Server (reposerver/server.go) - An internal gRPC service maintaining a local cache of Git repositories. It generates Kubernetes manifests by accepting repository URL, revision, application path, and template-specific settings (Helm values, parameters). The service uses a locking mechanism to prevent concurrent operations on the same repository revision.

Application Controller (controller/appcontroller.go) - A Kubernetes controller continuously monitoring applications and comparing live state against desired state. It detects drift (OutOfSync status), invokes user-defined lifecycle hooks (PreSync, Sync, PostSync), and optionally takes corrective action. Uses work queues and informers for efficient reconciliation.

ApplicationSet Controller (applicationset/controllers/applicationset_controller.go) - Reconciles ApplicationSet resources, generating multiple Application resources based on generators (Git, Cluster, List, etc.). Supports progressive sync strategies and manages application lifecycle including creation, update, and deletion.

Data Flow & Interactions

Loading diagram...

Key Architectural Patterns

Layered Dependencies - Components in upper layers (UI, Application) depend on lower layers (Core, Infrastructure), but never vice versa. This maintains clean separation of concerns.

Kubernetes-Native - Controllers use Kubernetes informers, work queues, and CRDs (Application, ApplicationSet, Project) for state management and event-driven reconciliation.

Caching Strategy - Redis provides a cache layer reducing requests to both the Kubernetes API and Git providers. Repository Server maintains local Git caches with revision-based locking.

gRPC Communication - Internal services communicate via gRPC with TLS support, metrics collection, and health checks. The API Server exposes both gRPC and REST (via grpc-gateway) endpoints.

Extensibility - The architecture supports plugins (CMP - Config Management Plugins), custom resource customizations, and notification integrations through well-defined interfaces.

Data Models & CRDs

Argo CD defines four primary Custom Resource Definitions (CRDs) that form the foundation of the system. These Kubernetes-native objects enable declarative GitOps workflows and multi-cluster application management.

Core CRDs

Application is the fundamental unit representing a deployed application. It specifies where to fetch manifests (source) and where to deploy them (destination), along with sync policies and health status. Applications support multiple sources, enabling complex multi-source deployments with Helm, Kustomize, or plain YAML.

ApplicationSet generates multiple Applications from a single template using generators (Git, cluster discovery, matrix, merge). This enables GitOps at scale, automatically creating applications for different environments, clusters, or teams without manual duplication.

AppProject provides logical grouping and access control. It defines which repositories can be used as sources, which clusters can be deployment destinations, RBAC roles, and JWT tokens for automation. Projects enforce security boundaries and enable multi-tenancy.

Repository stores connection details for Git, Helm, and OCI registries. It includes authentication credentials (SSH keys, tokens, TLS certs), connection state, and repository-specific settings like LFS support or OCI enablement.

Application Structure

type Application struct {
  TypeMeta   metav1.TypeMeta
  ObjectMeta metav1.ObjectMeta
  Spec       ApplicationSpec
  Status     ApplicationStatus
  Operation  *Operation
}

ApplicationSpec contains the desired state: source repository URL, target revision, destination cluster/namespace, sync policy, and optional source hydrator for manifest generation workflows.

ApplicationStatus tracks the current state: sync status (synced/out-of-sync), health status, resource list, sync history, and operation state. The status is continuously updated by the application controller.

Source Configuration

Applications support multiple source types through ApplicationSource:

• Git: Direct YAML manifests with optional Kustomize or Helm overlays
• Helm: Chart repositories with value overrides and parameters
• OCI: Helm charts stored in OCI registries
• Plugin: Custom config management plugins for specialized tools

Each source type has specific options (e.g., ApplicationSourceHelm for Helm parameters, ApplicationSourceKustomize for image/replica overrides).

Destination & Sync Policy

ApplicationDestination specifies the target: either a cluster server URL or cluster name, plus target namespace. SyncPolicy controls automation: auto-sync on source changes, prune resources, self-heal drift, and sync waves for ordered deployments.

AppProject Security Model

AppProject enforces multi-layer security:

• Source Repos: Whitelist of allowed Git/Helm repositories
• Destinations: Whitelist of allowed cluster/namespace combinations
• Roles: RBAC roles with policies (e.g., applications:get:*)
• JWT Tokens: Automation tokens scoped to roles for CI/CD integration

Projects validate uniqueness of destinations, prevent invalid wildcards, and support service account bindings for fine-grained access control.

Repository Credentials

RepoCreds and Repository store authentication details. RepoCreds are reusable credential templates matched by URL pattern. Repository objects include connection state tracking, TLS certificate data, SSH keys, GitHub App credentials, and proxy settings. The Type field distinguishes Git, Helm, and OCI repositories.

Data Flow

Loading diagram...

The controller reconciles Applications by fetching manifests from repositories (using credentials), rendering them with source-specific tools, and syncing to target clusters. AppProject policies are enforced at every step.

API Server & Services

The API Server is the central gRPC/REST gateway that exposes Argo CD's functionality to the Web UI, CLI, and CI/CD systems. It multiplexes HTTP/1.1 and gRPC protocols on a single port using CMux, with optional TLS support.

Architecture Overview

Loading diagram...

Core Components

ArgoCDServer is the main server struct that orchestrates all services. It manages:

• Service Set: Cluster, Repository, Application, Project, Session, Settings, Account, Certificate, GPG Key, and Notification services
• Informers: Kubernetes informers for Applications, AppProjects, and ApplicationSets for efficient caching
• Authentication: RBAC enforcement, session management, and OIDC/SSO integration
• Lifecycle: Graceful startup, settings watching, and signal-based shutdown

Service Layer

Each service implements specific domain logic:

• Application Service: CRUD operations, manifest generation, sync operations, and resource tree computation
• Repository Service: Repository credential management, connection validation, and app discovery
• Cluster Service: Cluster registration, authentication rotation, and connection state tracking
• Project Service: Project RBAC policies and resource restrictions
• Session Service: User authentication with rate limiting and token management

Request Flow

1. Multiplexing: CMux routes incoming connections to gRPC or HTTP handlers based on protocol detection
2. Authentication: gRPC interceptors validate JWT tokens and extract user claims
3. Authorization: RBAC enforcer checks permissions before executing operations
4. Service Execution: Domain-specific service handles the request
5. Response: Results marshaled to JSON (HTTP) or Protocol Buffers (gRPC)

Key Features

• Graceful Restart: Settings changes trigger server restart without dropping connections
• Health Checks: Liveness and readiness probes for Kubernetes deployments
• Metrics: Prometheus metrics for gRPC calls, HTTP requests, and cache operations
• Tracing: OpenTelemetry integration for distributed tracing across services
• Content Negotiation: Supports multiple content types with CSRF protection
• Compression: Optional GZIP compression for HTTP responses (except Server-Sent Events)

Configuration

The server accepts numerous flags for customization:

• Network: --address, --port, --metrics-address, --metrics-port
• Security: --insecure, --repo-server-strict-tls, --dex-server-strict-tls
• Features: --enable-gzip, --enable-proxy-extension, --hydrator-enabled
• Limits: --webhook-parallelism-limit, --repo-server-timeout-seconds
• Observability: --otlp-address, --loglevel, --logformat

Application Controller & Reconciliation

The Application Controller is the core reconciliation engine of Argo CD. It continuously monitors Application resources and ensures the live cluster state matches the desired state defined in Git. The controller runs multiple worker goroutines to process applications concurrently.

Reconciliation Loop

The reconciliation process follows these key stages:

1. Refresh Determination (needRefreshAppStatus): Checks if an application needs reconciliation based on:

   • Explicit refresh requests from users or the controller
   • Spec changes (source, destination, sync policy)
   • Expiration of the last reconciliation (soft timeout or hard timeout)

2. State Comparison (CompareAppState): Compares desired state (from Git) against live state (in cluster):

   • Fetches target manifests from the repository server
   • Retrieves live resources from the cluster cache
   • Performs diff analysis to identify out-of-sync resources
   • Calculates health status for all managed resources

3. Resource Management (setAppManagedResources): Builds and caches the application resource tree with sync status for each resource.

4. Auto-Sync (autoSync): If automated sync is enabled and the application is out-of-sync, initiates a sync operation respecting sync windows and policies.

5. Status Persistence: Updates the Application CRD with reconciliation results including sync status, health, and resource tree.

Work Queues

The controller uses multiple rate-limited work queues:

• appRefreshQueue: Processes application status reconciliation (default 20 workers)
• appOperationQueue: Handles sync operations (default 10 workers)
• appComparisonTypeRefreshQueue: Manages refresh requests with specific comparison levels
• projectRefreshQueue: Processes AppProject changes
• appHydrateQueue: Handles manifest hydration (when enabled)

Comparison Levels

Applications can be compared at different levels:

• ComparisonWithNothing (0): Only refresh resource tree without comparing desired vs. live state
• CompareWithRecent (1): Compare against the last synced revision
• CompareWithLatest (2): Compare against the latest Git revision
• CompareWithLatestForceResolve (3): Force resolve Git revision and compare (bypasses caching)

Health Assessment

The setApplicationHealth function evaluates resource health by:

• Checking each managed resource's health status using gitops-engine health rules
• Applying custom health overrides defined in the AppProject
• Aggregating individual resource health into overall application health
• Optionally persisting resource-level health in the Application CRD

Sync Operations

When a sync operation is initiated:

1. The controller creates an OperationState with phase Running
2. SyncAppState executes the sync using gitops-engine's reconciliation engine
3. Resources are applied in sync-wave order with configurable delays
4. The operation state is updated with progress and completion status
5. Upon completion, a refresh is automatically requested to update status

Sharding & Distribution

For multi-instance deployments, the controller supports:

• Cluster Sharding: Distributes applications across controller instances based on cluster assignment
• Dynamic Cluster Distribution: Automatically rebalances applications when controller replicas change
• Shard Mapping: Maintains a ConfigMap tracking which controller instance owns which shard

Key Configuration

Important flags control reconciliation behavior:

• --app-resync: Soft resync period (default 120s)
• --app-hard-resync: Hard resync period (default 0, disabled)
• --app-resync-jitter: Random jitter added to resync (default 60s)
• --status-processors: Number of reconciliation workers (default 20)
• --operation-processors: Number of sync operation workers (default 10)
• --sync-timeout: Maximum duration for a sync operation
• --self-heal-timeout-seconds: Delay between self-healing attempts

Repository Server & Manifest Generation

The Repository Server is a critical internal gRPC service that maintains a local cache of Git repositories and generates Kubernetes manifests for applications. It handles multiple source types (Git, Helm, Kustomize, OCI, and Config Management Plugins) and manages concurrent manifest generation with intelligent caching.

Architecture Overview

Loading diagram...

Server Initialization

The repository server starts via argocd-repo-server command, which:

1. Initializes core components in cmd/argocd-repo-server/commands/argocd_repo_server.go:

   • Creates a gRPC server with TLS support
   • Sets up metrics collection and health checks
   • Configures parallelism limits and resource constraints
   • Initializes GPG keyring for signature verification

2. Creates the Repository Service (reposerver/repository/repository.go):

   • Manages temporary directories for Git, Helm, and OCI sources
   • Maintains a semaphore for concurrent request limiting
   • Initializes cache backends (Redis or in-memory)

3. Registers gRPC services in reposerver/server.go:

   • RepoServerService for manifest generation
   • Version service for health checks
   • gRPC reflection for debugging

Manifest Generation Flow

When a manifest generation request arrives:

1. Cache Check: Looks up cached manifests using a composite key (revision, source config, namespace, tracking method)

2. Repository Lock: Acquires a lock to prevent concurrent modifications to the same repo/revision

3. Source Resolution: Determines source type and downloads/extracts the application path

4. Manifest Generation: Delegates to the appropriate handler:

   • Helm: Runs helm template with values resolution and dependency building
   • Kustomize: Executes kustomize build with patches and overlays
   • Git Directory: Applies Kustomize or custom generators to YAML files
   • OCI: Extracts OCI artifacts and processes manifests
   • Plugin (CMP): Streams application files to CMP sidecar for custom generation

5. Post-Processing: Applies resource tracking, overrides, and signature verification

6. Cache Storage: Stores generated manifests with TTL for future requests

Key Configuration Parameters

The RepoServerInitConstants struct controls behavior:

• ParallelismLimit: Maximum concurrent manifest generations (semaphore-based)
• MaxCombinedDirectoryManifestsSize: Size limit for directory-based manifests
• HelmManifestMaxExtractedSize: Helm chart extraction size limit
• OCIManifestMaxExtractedSize: OCI artifact extraction size limit
• PauseGenerationAfterFailedGenerationAttempts: Failure threshold before pausing
• CMPTarExcludedGlobs: Patterns to exclude when streaming to CMP servers

Caching Strategy

The cache layer (reposerver/cache/cache.go) stores:

• Manifest responses: Full generated manifests with metadata
• Git file listings: Directory contents for quick lookups
• Helm chart indices: Repository metadata for version discovery
• Revision metadata: Commit SHAs and signature verification results

Cache keys incorporate source configuration, cluster info, and namespace to ensure correctness across different deployment contexts.

Concurrency & Performance

• Repository Locks: Per-repo/revision locks prevent concurrent Git operations
• Parallelism Semaphore: Limits total concurrent manifest generations
• Async Generation: CMP requests use channels to unlock repos early while generation continues
• Metrics: Prometheus metrics track pending requests, generation latency, and cache hit rates

Error Handling & Resilience

• Pause Generation: After repeated failures, generation is paused for a configurable duration
• Signature Verification: Optional GPG signature verification for commit authenticity
• Resource Limits: Enforces maximum extracted sizes to prevent DoS attacks
• Graceful Shutdown: Drains in-flight requests before terminating

ApplicationSet Controller & Generators

Overview

The ApplicationSet Controller is a Kubernetes controller that automates the generation and management of Argo CD Applications at scale. It uses a generator-based architecture where generators produce parameters that are rendered into Application templates, enabling multi-cluster deployments and dynamic application generation.

Architecture

Loading diagram...

Core Components

ApplicationSetReconciler is the main controller that orchestrates the entire workflow. It:

• Watches ApplicationSet resources and responds to changes
• Invokes registered generators to produce parameters
• Renders parameters into Application templates
• Creates, updates, or deletes Applications in the cluster
• Manages progressive syncs and dependency ordering
• Tracks status and conditions

Generator System

Generators are pluggable components that produce parameter sets. Each generator implements the Generator interface with three methods:

• GenerateParams() - Returns a list of parameter maps
• GetRequeueAfter() - Controls reconciliation frequency
• GetTemplate() - Returns inline template overrides

Available Generators:

1. List - Static key/value pairs from a fixed list
2. Clusters - Targets registered Argo CD clusters with label selectors
3. Git - Generates from Git repository files or directory structure
4. SCMProvider - Integrates with GitHub, GitLab, Gitea for dynamic discovery
5. PullRequest - Creates Applications for pull requests
6. ClusterDecisionResource - Uses custom Kubernetes resources (duck-typing)
7. Plugin - Extensible plugin-based generation
8. Matrix - Combines two generators with cross-product logic
9. Merge - Combines multiple generators sequentially

Reconciliation Flow

Loading diagram...

Template Rendering

The GenerateApplications() function processes each generator in sequence:

1. Calls Transform() to convert generator specs into parameter sets
2. Applies label selectors for post-filtering
3. Renders parameters into the Application template using Go templating
4. Returns the final list of Applications to reconcile

Parameters are flattened and merged, allowing nested access like {{.cluster.name}}.

Progressive Syncs

When enabled, the controller can order Application syncs based on dependencies. It:

• Builds a dependency graph from Application annotations
• Syncs Applications in waves to prevent cascading failures
• Tracks sync progress in ApplicationSet status
• Supports rollout strategies for safer deployments

Key Features

• Multi-cluster targeting - Deploy to multiple clusters with a single resource
• Dynamic generation - Automatically respond to cluster additions/removals
• Template reuse - Single template with multiple parameter sources
• Validation - Validates generated Applications before creation
• Status tracking - Detailed status for each generated Application
• Webhook support - Triggers reconciliation from external events
• Metrics - Observability into reconciliation performance

Utilities & Helper Packages

The util package provides essential helper utilities that power ArgoCD's core functionality. These packages handle cross-cutting concerns like Git operations, Kubernetes interactions, caching, and security.

Git Operations

The git package manages repository interactions with support for SSH, HTTPS, and HTTP URLs. Key functions include URL normalization (NormalizeGitURL), commit SHA validation, and repository testing. The Client type wraps go-git with credential management, supporting SSH keys, OAuth tokens, and GitHub App credentials. Credentials are cached in-memory to avoid redundant API calls.

Kubernetes Integration

The kube package provides utilities for working with Kubernetes resources. SetAppInstanceLabel applies the standard app.kubernetes.io/instance label to resources and their pod templates. IsValidResourceName validates Kubernetes naming conventions. These utilities integrate with the gitops-engine for resource tracking and management.

ArgoCD Application Utilities

The argo package contains application-specific logic. AugmentSyncMsg enriches error messages with context about missing CRDs or API versions. FilterByProjects filters applications by project membership. The package also handles application conditions, validation, and integration with the gitops-engine for sync operations.

Diff & Resource Comparison

The diff package provides DiffConfigBuilder for safely constructing diff configurations. It integrates with normalizers to handle resource-specific comparison rules, managed fields, and aggregated roles. Diffs can be cached using the application state cache for performance optimization.

RBAC & Authorization

The rbac package implements role-based access control using Casbin. It defines resources (clusters, projects, applications, repositories) and actions (get, create, update, delete, sync). Policies are loaded from ConfigMaps and support both glob and regex matching modes. The enforcer validates user permissions against these policies.

Caching Layer

The cache package provides a multi-level caching abstraction with Redis and in-memory backends. CacheClient interface supports set, get, delete, and watch operations. TwoLevelClient combines Redis and in-memory caches for performance. Items support expiration, overwrite prevention, and deletion flags.

Database Abstraction

The db package abstracts Kubernetes ConfigMap storage for clusters, repositories, certificates, and GPG keys. ArgoDB interface provides methods for CRUD operations on these resources. The implementation uses Kubernetes client-go to interact with ConfigMaps in the ArgoCD namespace.

Helm & OCI Support

The helm package manages Helm chart repositories with index caching and OCI support. Client interface provides chart extraction, tag retrieval, and index management. The oci package similarly handles OCI image repositories with tag caching and manifest extraction.

Command Execution

The exec package wraps OS command execution with timeout handling, output redaction, and error logging. RunWithExecRunOpts supports configurable timeouts, stderr capture, and token redaction for sensitive output. Execution is traced for observability.

CLI & Command-Line Interface

Overview

The Argo CD CLI is built on Cobra, a powerful Go framework for creating command-line applications. The CLI provides a hierarchical command structure with subcommands for managing applications, projects, repositories, clusters, and more. It supports both interactive and headless modes, with extensibility through a plugin system.

Command Architecture

The CLI follows a tree-based command hierarchy:

Loading diagram...

Root Command (NewCommand() in root.go):

• Initializes global client options and Kubernetes path options
• Registers all top-level subcommands
• Configures persistent flags for server connection, authentication, and logging

Subcommands are organized by resource type:

• app – Manage applications
• proj – Manage projects
• repo – Manage repositories
• cluster – Manage clusters
• admin – Administrative operations (requires Kubernetes access)

Global Flags

All commands inherit persistent flags from the root command:

--server              Argo CD server address
--auth-token          Authentication token
--config              Path to Argo CD config file
--plaintext           Disable TLS
--insecure            Skip server certificate verification
--core                Talk directly to Kubernetes instead of API server
--port-forward        Use port forwarding to connect
--grpc-web            Enable gRPC-web protocol
--loglevel            Set logging level (debug|info|warn|error)
--logformat           Set logging format (json|text)

Plugin System

Argo CD supports extending the CLI with custom plugins. The plugin system works by:

1. Plugin Discovery: Searches PATH for executables matching the pattern argocd-<command-name>
2. Command Execution: When an unknown command is encountered, the CLI attempts to find and execute a matching plugin
3. Error Handling: If a command is not recognized as a built-in command, HandleCommandExecutionError() in plugin.go attempts plugin resolution

Plugin Naming Convention:

argocd-mycommand    # Executable for 'argocd mycommand'
argocd-foo-bar      # Executable for 'argocd foo bar'

Plugins receive all remaining arguments and inherit the parent process environment, allowing full integration with the CLI.

Command Initialization Pattern

Commands use the InitCommand() wrapper from initialize/cmd.go to support headless mode. This allows the CLI to:

• Start an Argo CD API server on-the-fly when needed
• Automatically configure client options to use the started server
• Support direct Kubernetes access via the --core flag

Example command registration in root.go:

command.AddCommand(initialize.InitCommand(NewApplicationCommand(&clientOpts)))
command.AddCommand(initialize.InitCommand(NewProjectCommand(&clientOpts)))

Output Formatting

Commands support multiple output formats via the PrintResource() and PrintResourceList() helpers in common.go:

• YAML (default): Human-readable structured format
• JSON: Machine-parseable format with indentation

Example usage:

argocd app get my-app -o json
argocd proj list -o yaml

Authentication & Configuration

The CLI stores configuration in a local config file (default: ~/.config/argocd/config). The login command handles:

• Username/password authentication
• SSO (Single Sign-On) via OIDC
• Token-based authentication
• TLS certificate configuration

Configuration is managed through ClientOptions and persisted via the localconfig package.

Web UI & Frontend

The Argo CD web UI is a React-based single-page application (SPA) that provides a comprehensive interface for managing GitOps deployments. Built with TypeScript and Webpack, it communicates with the backend API to display application status, manage deployments, and configure repositories and clusters.

Architecture Overview

Loading diagram...

Core Technology Stack

The UI uses modern frontend technologies:

• React 16.9 with TypeScript for type-safe component development
• React Router for client-side navigation and routing
• RxJS for reactive state management and data streams
• Webpack 5 for bundling and development server
• Argo UI library for shared UI components and styling
• Monaco Editor for YAML editing capabilities
• XTerm for terminal/log viewing

Main Application Structure

The application is organized into feature modules:

• Applications (ui/src/app/applications/) - Core module for viewing and managing applications, including deployment history, resource trees, and sync operations
• Settings (ui/src/app/settings/) - Configuration for repositories, clusters, projects, and credentials
• Login (ui/src/app/login/) - Authentication and SSO integration
• Help (ui/src/app/help/) - Documentation and support resources
• Shared (ui/src/app/shared/) - Reusable components, services, and utilities

Key Components

App.tsx serves as the root component, managing:

• Route definitions and navigation
• Global state (popups, notifications, version info)
• Theme preferences and authentication settings
• Layout wrapper with sidebar navigation

ApplicationDetails is the most complex component, displaying:

• Application status and sync state
• Resource tree visualization with dependency graphs
• Pod logs and container terminals
• Deployment history and operation states
• Real-time updates via WebSocket subscriptions

Service Layer

Services in ui/src/app/shared/services/ handle API communication:

• ApplicationsService - CRUD operations for applications
• RepositoriesService - Git repository management
• ClustersService - Kubernetes cluster configuration
• AuthService - Authentication and SSO settings
• ViewPreferencesService - User preferences and theme settings
• ExtensionsService - Plugin system for custom UI extensions

Development Workflow

yarn install          # Install dependencies
yarn start            # Launch webpack dev server on port 3000
yarn build            # Build production bundle to ./dist
yarn lint --fix       # Run ESLint with auto-fix
yarn test             # Run Jest test suite

The dev server supports hot module reloading for rapid iteration. The production build is embedded in the backend binary via embed.go and served as static assets.

State Management Pattern

The UI uses RxJS Observables for reactive data flows rather than Redux. Components subscribe to observable streams from services, which handle API calls and caching. This pattern enables real-time updates and efficient re-rendering through React's subscription model.