Architecture Overview
Technical reference. This page is for integrations, advanced configuration, or platform operations. For portal tasks, start with the user guide.
Orqestra is an internal AI control plane. It is not a single AI application and it is not a generic infrastructure bundle.
Its role is to provide a governed, reusable path for internal AI workloads so that teams inherit identity, policy, tracing, release, and asset-access controls instead of rebuilding them independently.
The repository architecture documents describe this control-plane baseline. The newer market-leadership and resilience specs extend that baseline without replacing it.
Visual Overview
System Components
Platform Interfaces
Operator-facing and consumer-facing entry points:
- Portal UI — Next.js App Router application for operators and consumers
- Workload API — FastAPI-based REST API with OpenAPI contracts
- Automation and SDK surfaces — programmatic access for CLI, agents, and declarative pipelines
Policy and Decision Services
- Service-lane classification
- Access and entitlement checks
- Approval-aware control evaluation
- Policy decisions required before execution
Runtime Gateway
- Approved provider access (LLM providers via LiteLLM gateway)
- Runtime mediation and bounded tool/action execution
- Runtime policy enforcement at execution time
Lifecycle Services
- Artifact versioning and promotion
- Rollback and release-state management
- Environment movement discipline
Evidence Services
- Execution traces and audit records
- Evaluation evidence
- Release evidence assembly
Asset Integration Layer
- Governed access to approved data and knowledge assets
- Source traceability
- Entitlement-aware retrieval paths
Deployment Topology
The local deployment uses Docker Compose with the following services:
| Service | Technology | Purpose |
|---|---|---|
| Control Plane | FastAPI (Python) | Core API, asset governance, release management |
| Portal | Next.js (React) | Operator and consumer UI |
| PostgreSQL | PostgreSQL 17 + pgvector | Persistent state, full-text search, and control-plane semantic-memory vector indexes. App traffic flows through PgBouncer; only direct-mode paths (Alembic, WORM, seed, CLI audit, Makefile DB helpers) connect to Postgres directly. |
| PgBouncer | PgBouncer 1.23 | Transaction-mode connection pooler in front of Postgres. App-tier SQLAlchemy pools (per-replica) talk to a bounded upstream pool of 30 + reserve 5 connections. query_wait_timeout=30, idle_transaction_timeout=60, client_idle_timeout=600. |
| Redis (×4, split by role) | Redis | redis-queue (Celery broker / result backend), redis-cache (asset and release caches), redis-coordination (leases, audit chain head, governor TPM windows), redis-signals (execution kill / pause TTL keys). Each instance gets its own memory budget and eviction policy. |
| Object Storage | S3-compatible (MinIO) | Artifact and evidence storage |
| LLM Gateway | LiteLLM | Provider-agnostic LLM access |
Key Design Decisions
- Separation of concerns: interfaces, policy, runtime, lifecycle, evidence, and asset access are independent layers.
- Provider-agnostic: the provider layer is replaceable; internal consumers never bind directly to provider-specific implementations.
- Evidence as a product requirement: execution tracing and audit capture are first-class, not afterthoughts.
- Release-centric data model: all governed assets flow through versioning, promotion, and release-state management.
- Multiple consumer surfaces: every capability is accessible via portal, API, CLI, declarative config, and agent interfaces.
Architectural Guardrails
- Do not start from a monolith that mixes provider calls, policy rules, and UI behaviour in one code path.
- Keep the provider layer replaceable.
- Treat evidence capture as a product requirement.
- Do not bind internal consumers directly to provider-specific implementations.
Current Product Scope
The first meaningful version proves one end-to-end governed path for an anchor workload with:
- Identity and access control
- Provider and runtime mediation
- Evidence and tracing
- Versioning and release control
- One governed data or knowledge access path
Source Documents
Supporting detail lives in:
docs/product/project-brief.mddocs/product/platform-vision.mddocs/architecture/ARCHITECTURE.mddocs/reference/control-plane-capability-model.mddocs/reference/system-architecture.mddocs/roadmap/2026-04-15-enterprise-platform-roadmap-matrix.mddocs/operations/deployment-topology.mddocs/operations/release-readiness-matrix.mddocs/resilience/backup-restore-runbook.md