# choreo-idp/choreo architecture

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

- Interactive diagram: https://gitdiagram.com/choreo-idp/choreo
- Repository: https://github.com/choreo-idp/choreo

## Overview

##### Project Overview
- OpenChoreo is an open-source internal developer platform (IDP). It targets both platform engineers (who need a customizable, production-grade platform) and developers (who want to focus on building and deploying applications without deep infrastructure concerns).
- The project provides capabilities such as CI/CD integration, API management, deployment pipelines, and Kubernetes integrations.

##### Key Components
a. Command Line Interface (CLI):
- Files under cmd/choreoctl, pkg/cli, and internal/choreoctl indicate that there is a primary CLI tool used by operators and developers.
- This as one component that serves command and control functions.
b. API and CRDs:
- The api directory and accompanying CRD definition files in config/crd and install/helm/choreo indicate that OpenChoreo defines custom resources. These CRDs are central to its integration with Kubernetes.
- Resources as part of the API layer that manages objects like deployments, components, environments, and pipelines.
c. Controller/Operator Components:
- A large part of the code is under internal/controller. This represents a set of controllers (or reconciler mechanisms) handling various CRDs such as builds, deployments, organizations, etc.
- Several separate controllers for resources like deployments, components, endpoints, and environments, connected to the API layer.
d. Kubernetes Integration:
- The overall system is designed to run on Kubernetes. It integrates with Kubernetes via custom controllers, webhooks (internal/webhook), and CRD installations.
- This should be shown as a container orchestration layer that interacts with the controllers and the underlying resources.
e. Configuration and Deployment Tools:
- The presence of various configuration files (e.g., Dockerfile, Makefile, Helm charts under install/) and sample deployment manifests suggests a structured deployment mechanism.
- This part as the deployment management and configuration layer.
f. Additional Supportive Components:
- The repository contains testing directories, documentation, and samples. While not core to runtime architecture, they are significant for understanding development, testing, and extension points.

##### Interactions and Relationships
- CLI (choreoctl) interacts with the API server (or Kubernetes cluster) to create, update, and query custom resources.
- The API layer (CRDs) serves as the data model, where each CRD (builds, deployments, etc.) is defined.
- Controllers watch for changes in these custom resources and implement the reconciliation loops for resource management.
- The deployment tool (Helm charts and configurations) is used to install and update the system components inside the Kubernetes cluster.

##### Architectural Patterns and Design Principles
- Controller Pattern: The system heavily uses Kubernetes controllers to reconcile desired state.
- Separation of Concerns: The CLI, API definitions, controller logic, and deployment configurations are all well separated.
- Extensibility: OpenChoreo makes use of CRDs and modular controllers, allowing for easy extension and integration with external systems.
- Declarative Configuration: The design leverages declarative configurations (Helm, YAML files) to manage deployments and resources.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Interaction Layer"
        CLI["Command Line Interface"]:::cli
    end

    subgraph "API Layer"
        API["API & CRDs"]:::api
    end

    subgraph "Controller Layer"
        CTRL["Controllers & Operators"]:::ctrl
    end

    subgraph "Kubernetes Cluster"
        KUBE["Kubernetes Integration"]:::kube
    end

    subgraph "Deployment Layer"
        DEPLOY["Deployment & Configuration"]:::deploy
    end

    subgraph "Supportive Artifacts"
        SUPPORT["Support Components"]:::support
    end

    CLI -->|"sends_commands"| API
    API -->|"watches_changes"| CTRL
    CTRL -->|"reconciles_to"| KUBE
    DEPLOY -->|"deploys_updates_to"| KUBE
    CLI -->|"triggers_deployments"| DEPLOY
    DEPLOY -->|"installs_CRDs_to"| API

    click CLI "https://github.com/choreo-idp/choreo/tree/main/cmd/choreoctl"
    click CLI "https://github.com/choreo-idp/choreo/tree/main/pkg/cli"
    click CLI "https://github.com/choreo-idp/choreo/tree/main/internal/choreoctl"

    click API "https://github.com/choreo-idp/choreo/tree/main/api"
    click API "https://github.com/choreo-idp/choreo/tree/main/config/crd"
    click API "https://github.com/choreo-idp/choreo/tree/main/install/helm/choreo/crds"

    click CTRL "https://github.com/choreo-idp/choreo/tree/main/internal/controller"

    click KUBE "https://github.com/choreo-idp/choreo/tree/main/internal/webhook"
    click KUBE "https://github.com/choreo-idp/choreo/blob/main/config/manager/manager.yaml"

    click DEPLOY "https://github.com/choreo-idp/choreo/tree/main/Dockerfile"
    click DEPLOY "https://github.com/choreo-idp/choreo/tree/main/Makefile"
    click DEPLOY "https://github.com/choreo-idp/choreo/tree/main/config"
    click DEPLOY "https://github.com/choreo-idp/choreo/tree/main/install/helm/choreo"

    click SUPPORT "https://github.com/choreo-idp/choreo/tree/main/docs"
    click SUPPORT "https://github.com/choreo-idp/choreo/tree/main/samples"
    click SUPPORT "https://github.com/choreo-idp/choreo/tree/main/test"

    classDef cli fill:#AED6F1,stroke:#1B4F72,stroke-width:2px;
    classDef api fill:#A9DFBF,stroke:#196F3D,stroke-width:2px;
    classDef ctrl fill:#F9E79F,stroke:#B9770E,stroke-width:2px;
    classDef kube fill:#D6EAF8,stroke:#2874A6,stroke-width:2px;
    classDef deploy fill:#FADBD8,stroke:#C0392B,stroke-width:2px;
    classDef support fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
