# ctrlplanedev/ctrlplane architecture

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

- Interactive diagram: https://gitdiagram.com/ctrlplanedev/ctrlplane
- Repository: https://github.com/ctrlplanedev/ctrlplane

## Overview

- Core Services:
- Web Service: This is the frontend application (found in apps/webservice) that provides the user interface for managing workspaces, deployments, resources, environments, etc.
- Event Worker: (apps/event-worker) processes asynchronous events from the event queue and is responsible for background processing.
- Jobs Service: (apps/jobs) manages job execution and monitoring tasks.
- Core Packages (Modules/Libraries):
- Validators: (packages/validators) ensures data integrity for entities like resources, deployments, and jobs.
- Auth: (packages/auth) handles authentication and authorization.
- Rule Engine: (packages/rule-engine) is used for evaluating policies and deciding how deployments should be processed.
- Job Dispatcher: (packages/job-dispatch) oversees job creation, updates, and dispatching.
- Release Manager: (packages/release-manager) manages the lifecycle of releases and deployments.
- Events System: (packages/events and possibly parts of job-dispatch) implements pub/sub capabilities to broadcast system-wide events.
- Core Concepts (Domain Entities):
- Resources: Represent deployable entities (e.g., Kubernetes clusters, VMs) that can be versioned.
- Systems: Logical groupings of resources.
- Environments: Deployment contexts such as development, staging, and production.
- Deployments: The operational process of applying a specific release (managed by components like release manager and jobs service).

- The Web Service (UI) sends user requests to backend APIs (in packages/api) that interact with authentication, rule engine, and validators.
- Upon user actions, the Web Service may trigger job creation through the Job Dispatcher.
- The Event Worker listens to events (job status updates, resource changes) published by the Events System.
- The Release Manager coordinates with the Rule Engine and Job Dispatcher to manage the deployment lifecycle.
- The Auth service is integrated into all API endpoints to ensure secured communication.
- The Validators perform data integrity checks across these interactions.
- That the flow of data is logically traced from user interactions (frontend) through backend orchestration to the actual updates on deployments.

##### Architectural patterns
- The system uses a separation of concerns with dedicated applications for web UI, background processing (event worker), and job management.
- Microservices (or modular monolith) based on packages and apps show high cohesion between domain logic (auth, validations, rule evaluation) and operational workflows (job dispatch, release management).
- Pay attention to how API routes (in packages/api) centralize communication between frontend and backend services.

##### Relevant technologies and frameworks
- Frontend: Built with Next.js (as indicated by next.config.js, page.tsx files) with rich client-side React components.
- Backend: Node.js environment supporting TypeScript code found across apps and packages.
- Docker and Kubernetes: Dockerfiles present under most apps and integrations point to containerized deployments.
- CI/CD: GitHub workflows and docker-compose files are used to orchestrate development services.
- Other integrations include support for Redis (for caching or queueing) and various third-party integrations for job coordination.

## Diagram (Mermaid)

```mermaid
graph TB
  %% Core Services
  subgraph "Core Services"
    WS["Web Service UI"]:::service
    EW["Event Worker"]:::service
    JS["Jobs Service"]:::service
  end

  %% Core Packages
  subgraph "Core Packages"
    VAL["Validators"]:::package
    AUTH["Auth Service"]:::package
    RULE["Rule Engine"]:::package
    JD["Job Dispatcher"]:::package
    RM["Release Manager"]:::package
    EVS["Events System"]:::package
  end

  %% Core Concepts
  subgraph "Core Concepts"
    RES["Resources"]:::concept
    SYS["Systems"]:::concept
    ENV["Environments"]:::concept
    DEP["Deployments"]:::concept
  end

  %% Relationships - Core Services to Core Packages
  WS -->|"calls"| AUTH
  WS -->|"validates"| VAL
  WS -->|"triggers"| JD
  AUTH -->|"secures"| WS
  VAL -->|"confirms"| WS

  %% Relationships - Within Core Packages
  RULE -->|"feeds"| JD
  JD -->|"dispatches to"| JS
  RM -->|"manages"| DEP
  EVS -->|"publishes"| EW
  EVS -->|"notifies"| JD

  %% Relationships - Core Services to Core Concepts
  JS -->|"monitors"| DEP

  %% Relationships - Core Concepts interconnections
  RES -->|"forms"| DEP
  SYS -->|"aggregates"| RES
  ENV -->|"hosts"| DEP

  %% Styles
  classDef service fill:#cfe2f3,stroke:#1f497d,stroke-width:2px;
  classDef package fill:#fce5cd,stroke:#b45f06,stroke-width:2px;
  classDef concept fill:#d9ead3,stroke:#38761d,stroke-width:2px;

  %% Click Events
  click WS "https://github.com/ctrlplanedev/ctrlplane/tree/main/apps/webservice"
  click EW "https://github.com/ctrlplanedev/ctrlplane/tree/main/apps/event-worker"
  click JS "https://github.com/ctrlplanedev/ctrlplane/tree/main/apps/jobs"
  click VAL "https://github.com/ctrlplanedev/ctrlplane/tree/main/packages/validators"
  click AUTH "https://github.com/ctrlplanedev/ctrlplane/tree/main/packages/auth"
  click RULE "https://github.com/ctrlplanedev/ctrlplane/tree/main/packages/rule-engine"
  click JD "https://github.com/ctrlplanedev/ctrlplane/tree/main/packages/job-dispatch"
  click RM "https://github.com/ctrlplanedev/ctrlplane/tree/main/packages/release-manager"
  click EVS "https://github.com/ctrlplanedev/ctrlplane/tree/main/packages/events"
```
