Skip to Content
Technical architectureControl Plane

Control Plane

Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.

The control plane is the core backend service of Orqestra. It exposes a REST API for managing governed assets, workloads, releases, and bindings.

Technology

  • Framework: FastAPI (Python)
  • Database: PostgreSQL with SQLAlchemy ORM
  • Background jobs: Celery with the queue-role Redis as broker / result backend (redis-queue); coordination-role Redis (redis-coordination) holds workspace leases and audit chain-head state.
  • Object storage: S3-compatible (provider-agnostic abstraction)

Service Structure

The control plane is a single FastAPI application located at services/control-plane/. The entry point is main.py, which assembles the application and mounts API routers.

Module Layout

services/control-plane/src/orqestra_control_plane/
  api/            # FastAPI routers and request/response validation
  auth/           # Authentication and authorization
  cache/          # Caching layer
  db/             # Database engine, session management, migrations
  models/         # SQLAlchemy ORM models (GovernedAsset, AssetVersion, etc.)
  orchestration/  # Workflow orchestration and flow execution
  repositories/   # Data access layer (repository pattern)
  storage/        # Object storage abstraction (S3-compatible)
  config.py       # Workload configuration
  main.py         # FastAPI app assembly and startup

Repository Pattern

Data access is mediated through repository classes rather than direct ORM queries in route handlers. Each domain entity has a corresponding repository that encapsulates query logic:

  • Repositories accept a database session and return domain models.
  • Route handlers depend on repositories, not on raw SQLAlchemy queries.
  • This keeps the API layer thin and the data access layer testable.

API Layer

The API layer uses FastAPI routers organised by domain:

  • Assets: CRUD for governed assets and asset versions
  • Workloads: consumer workload registration and configuration
  • Releases: release record creation, state transitions, and promotion
  • Bindings: release-asset binding management
  • Namespaces and workspaces: tenant hierarchy, workspace membership, and resource attribution
  • Connections and secrets: workspace connection instances and secret metadata
  • Templates and model catalog: bundled template apply and runtime model inventory
  • Hooks, memory, and evidence: governed runtime extensions and execution evidence
  • Execution control: pause, resume, kill, snapshot, and recovery endpoints

All endpoints produce OpenAPI-documented contracts. Request and response validation is handled by Pydantic models.

Configuration

Workload configuration is loaded from environment variables via config.py. Secrets and connection strings are never hardcoded. The Docker Compose setup provides a .env.docker file for local development defaults.

Auth and authorization

Every tenant-scoped endpoint is evaluated against an ActorContext. Permission checks are explicit at route boundaries and use workspace or organization scope depending on the resource. Internal service calls are allowed only through service-auth paths and are still scoped before data-plane operations execute.

The control plane also writes governance audit rows for security-sensitive mutations such as asset creation, release transitions, template apply, connection changes, secret reveals, share grants, and entitlement revocation.

Runtime integration

The control plane does not run user workload logic directly. It resolves the active release, asset bindings, subject context, model configuration, connection metadata, policy posture, and evidence settings, then dispatches to runtime-gateway. Streaming execution is proxied as SSE without converting it into a buffered JSON response.

This split keeps control-plane responsibilities focused on governance, tenancy, lifecycle, and durable records while runtime-gateway owns execution, provider calls, hooks, egress controls, and secret resolution.

Background work

Celery workers handle scheduled and asynchronous control-plane jobs, including governance rollups, lifecycle tasks, audit verification, WORM export, evidence lifecycle work, and resource-governor maintenance. Redis roles are separated so queue traffic, cache traffic, coordination leases, and signals do not collapse into one operational channel.

Storage responsibilities

PostgreSQL owns transactional state: hierarchy, assets, versions, releases, executions, audit, evidence metadata, memory metadata, permissions, and connection records. Object storage owns larger JSON artifacts, evidence payloads, checkpoint payloads, and archive/export records. The asset API stores both a database copy and an artifact reference for version content so reads stay fast while integrity checks can still use checksums and object-store artifacts.

Failure posture

Control-plane routes fail closed at trust boundaries:

  • missing workspace context on scoped asset reads returns an error
  • invalid asset content is rejected before version creation
  • activation rejects incomplete release bindings or incompatible provider posture
  • audit-chain append failures block security-sensitive mutations where required
  • retrieval entitlements and secret reveals are audited rather than treated as ordinary reads

For the entity model behind these flows, see Data Model.

Architecture OverviewData Model