Skip to Content
Technical architectureTechnical: Architecture Decisions

Architecture Decisions

Orqestra records significant technical decisions as Architecture Decision Records (ADRs). Each ADR captures the context, decision, and consequences for a specific choice.

The source files live in docs/adr/ in the repository.

This index is generated automatically from the ADR files by apps/docs/scripts/generate-adr-index.mjs. CI fails the build if this page drifts from the ADR directory.

ADR Index

#DecisionStatus
0001Position Orqestra As An Internal AI Control Plane Accepted
0002Preserve Separation Of Control-Plane Concerns Accepted
0003Keep The Repository Stack-Agnostic Until Phase 1 Design Is Closed Superseded by ADR 0005
0005Use React For Frontend And Python For Backend Accepted
0006Adopt A Tailored TOGAF-Style Architecture Method Accepted
0007Select A Governed Internal Knowledge Assistant As The Phase-1 Anchor Workload Accepted
0009Realize V1 As A Modular Control-Plane Core With A Separate Runtime Gateway Accepted
0010Use Next.js App Router For The Portal Frontend Accepted
0011Use FastAPI For Platform APIs And Control-Plane Services Accepted
0012Use PostgreSQL And S3-Compatible Object Storage For State, Artifacts, And Evidence Accepted
0013Use Enterprise OIDC/OAuth2 Integration And OpenAPI-Based Service Contracts Accepted
0014Use Celery With Redis For Background Jobs In Phase 1 Accepted
0015Use OpenAI Responses API With GPT-5 Mini As The First Provider Path Superseded by ADR 0031
0016Use Markdown-Aware Chunking And PostgreSQL Full-Text Retrieval For The Initial Corpus Accepted
0017Use Pnpm, Uv, And Docker Compose As The Local Development Baseline Accepted
0018Use Authorization Code With PKCE For The Portal And Workload Identity Patterns For Non-User Access Accepted
0019Adopt A Release-Centric Control-Plane Data Model For Phase 1 Accepted
0020Use A Minimum Governed Release-State Model For Phase 1 Accepted
0021Use Workload-Owned Policy Bundles And Versioned Decision Envelopes In Phase 1 Accepted
0022Model Evidence As Linked Execution Packages And Release Evidence Bundles Accepted
0024Adopt Pilot-Class Service Targets For Phase 1 Accepted
0025Use agentic-engagement As The First Reference Non-Portal Consumer Path Accepted
0026Use Native Pnpm, Uv, And Docker Compose Commands Before Adding Task Wrappers Superseded by ADR 0029
0027Portal Serves Both Operators And Consumers With Separable Surfaces Accepted
0028Use Provider-Agnostic Object Storage Abstraction Accepted
0029Use Make As The Project Task Runner Accepted
0030Use Simple PostgreSQL Full-Text Search For Initial Retrieval Accepted
0031Use LiteLLM As The Provider-Agnostic Gateway With Governed Route Reconciliation Accepted
0032Support Multiple Orchestration Patterns With Graph-Based Flow Model Accepted
0033Second Workload Extensibility Proposed
0034Portal Proxy SSRF Allowlist Pattern Accepted
0035Service-to-Service Authentication via Static Bearer Token Largely superseded — see the amendments below for the current
0036Platform Events via Redis Pub/Sub (CloudEvents Deferred) Accepted
0037Adopt Namespace/Workspace Hierarchy for Multi-Tenancy Accepted
0038Defer CloudEvents Adoption Accepted
0039Portal Workspace Context Selector UX Pattern Accepted
0040HashiCorp Vault for Secret Management Accepted
0041Organization Entity, First-Run Onboarding, and Admin Plane Separation Accepted
0042Connections and Secrets Management Model Accepted
0043Permission Management UI Accepted
0044Operationalize Distribution-Aware Organization Onboarding Accepted
0045Portal visual language refresh Accepted — typography and color decisions superseded by ADR 0086 ; structural principles remain in force
0046Governance KPI Endpoint Scope Accepted
0047Platform Admin Versus Permission Model Accepted
0048CLI-SDK Async Contract Accepted
0049Celery Worker AsyncEngine Lifecycle Accepted
0050Execution Evidence Graph Read Model Accepted
0051Runtime Gateway Oversize Evidence Handling Accepted
0052Runtime-gateway step-execution error classification Accepted
0053Subflow execution lineage and wiring Accepted
0054Fail Closed When workspace_id Is Missing on Data-Access EndpointsSuperseded by ADR 0060 
0055Automated Penetration Test Suite Accepted
0056Pen-Test Suite Phases 2–5 Rollout Accepted
0057Governance Spine Hash-Chained Audit + Two-Layer WORM + Workload Terminology Follow-Up Accepted
0058Agent-Trap Probe Framework Proposed (egress allowlist and SSRF guard satisfied via ADR-0059; retrieval-memory quarantine and hybrid egress filtering remain open)
0059Runtime-Gateway Outbound HTTP Plugins Must Pass Allowlist And SSRF Guard Accepted — landed via the commits listed under Implementation.
0060Organization-Scoped Permissions and the Scope Chain Accepted
0061Role/Permission Privilege Separation Accepted
0062Resource Governor Admission Control Accepted
0063Provider TPM And Organization Daily Cost Pools Accepted
0064Outbound Egress Proxy and Audit Boundary Accepted
0065Governed Provider Plane Accepted
0066Provider Transport Foundation Accepted
0067User-Bound Identity and Knowledge Entitlements Accepted
0068Observability Correlation Contract Accepted
0069Kubernetes Delivery Hardening Accepted
0070Control-Plane Memory Vector Recall Accepted
0071Test Reliability Tier Model Accepted
0072Evidence Lifecycle Service Accepted
0073External Runtime Conformance And Certification Authority Accepted
0074Asset Builder Shell And Asset-Kind Adapters Accepted
0075Provider Lane Posture And Claim-Level Ownership Accepted
0076On-Behalf-Of Delegated Identity And The Identity Broker Accepted
0077Runtime Dispatch Redis Role Accepted
0078Control-Effectiveness System-of-Record And Advisory Evaluator Accepted
0079AI Dependency / Control-Lineage Graph Closure Accepted
0080Licensing And Edition Model Accepted
0081Self-Hosted Inference Is Governed Capability Metadata And Evidence Accepted
0082AI Dependency Quarantine Record And Value Ownership Accepted
0083Cross-Cutting Enforcement-Assurance-Tier Vocabulary Proposed
0084Indexed/Hybrid Retrieval Escalation Gated By A Retrieval-Quality Eval Harness Proposed
0085Governed Vector-Store Backend Interface Accepted (amended)
0086Portal visual language v2 Accepted (brand color, surface depth, and consumer-surface scope superseded by ADR 0087 ; typography scale, text ladders, borders, and the identifier/loading-gate pattern rules remain in force)
0087Portal visual language v3 — Control Tower (Spectrum / Aurora) Accepted
0088Roadmap Sequencing — Federated Control Tower (R4) Advancing Ahead Of The Governed Provider Plane (R2) Proposed
0089Defer Dedicated Service-Lane Classification And Employee-Impact Pre-Deployment Hold Proposed
0090Tool Contract — Author-Declared Side-Effect-Class Enum And Structured Error-Response Contract Accepted
0091Mandatory Knowledge-Base Certification For External-Runtime Retrieval Accepted
0092Governed Environment Ladder And Per-Environment Config Isolation (DTAP) Accepted (governed ladder, posture resolution, L1 config isolation, L2 network zones, and the L3 manifest export/import contract are implemented; asset-side slot declarations and GitOps sync automation remain — see Follow-on work)
0093Experiment Execution Context And Two-Level Experiment Cost Budgets Proposed
0094Fenced replay for generated evaluation candidates Accepted
0095Race-safe imported-read primitive lives in the plugin SDK Accepted
0096Retire the unbound MCP authorization-code flow Accepted
0097Generate A Private Local Compose Credential Bundle Accepted
0098Bounded Outbound Response Materialization Accepted
0099Defer Durable Workflow Engine Adoption Pending Measured Need Accepted
0100Reserved Retrieval-HMAC Key Family With Purpose AppRoles Accepted
0101Make Orqestra Documentation Repository-Local Accepted
0102Governed A2A Protocol Profile Accepted
0103Durable Containment Operator Surfaces Accepted
0104Process-Local Entra Workload Token Source Accepted
Multi-Tenancy