Architecture Decision Records
kora records every significant technical decision as an ADR. This index is the catalogue.
Naming. ADR files are named YYYY-MM-DD-kebab-slug.md — the decision date plus a short slug. There is no sequential number; the slug is the citation handle (e.g. inference-gateway-architecture). Files sort chronologically. The original sequential numbers are preserved in the Former # column below for traceability with older commits and discussions. To add one, copy template.md and follow the contributing workflow.
Status values: Proposed (under discussion) · Accepted (ratified; may or may not be fully implemented) · Deprecated / Superseded.
By subsystem
Foundations & Platform
- Monorepo Technology Stack —
Accepted· 2026-02-16 - Language and Framework Selection (Go & Next.js) —
Accepted· 2026-02-16 - Repository Pattern and Code Organization —
Accepted· 2026-02-17 - OTEL-Compatible Dependency-Injected Logging —
Accepted· 2026-02-17 - Controller-Based HTTP Routing with Stdlib ServeMux —
Accepted· 2026-02-17 - YAML File-Based Configuration with Typed Generic Loader —
Accepted (Amended 2026-10-06)· 2026-02-18 - Database Infrastructure Layer —
Accepted· 2026-03-03 - Multi-Service Backend Deployment Structure —
Accepted· 2026-03-19 - OpenTelemetry Observability Discipline —
Accepted· 2026-03-21 - Prometheus Metrics Endpoints for Backend Services —
Accepted· 2026-10-06 - Local Development Environment —
Superseded· 2026-03-10 - Kubernetes-Only Local Development —
Accepted· 2026-07-10 - CI Pipeline and Local Build Parallelisation —
Proposed· 2026-07-21 - Rendered Service Config Files —
Accepted· 2026-10-06
Identity, Auth & Tokens
- Unified Identity Model —
Accepted· 2026-03-05 - SPIFFE/SPIRE Workload Attestation —
Accepted· 2026-03-05 - OIDC Provider Abstraction and Local Identity Provider —
Accepted· 2026-03-16 - Dynamic SPIFFE Identity Grants and Tenant Isolation —
Accepted· 2026-03-17 - Tenant Registration and OIDC Provider Binding —
Accepted· 2026-03-31 - OIDC Client Secret Projection for Confidential Tenants —
Accepted· 2026-03-31 - Browser-Based Authentication Flow and BFF Session Architecture —
Accepted· 2026-04-01 - Home Realm Discovery and Email-Based Tenant Routing —
Accepted· 2026-04-01 - Personal Access Tokens for Inference —
Accepted· 2026-04-02 - User Profiles Table for Principal Attribution —
Accepted· 2026-04-19 - User App Preferences —
Proposed· 2026-05-08 - Envoy ext_proc Sidecar for Transparent Platform Token Injection —
Accepted· 2026-03-21 - OAuth2 Web-Redirect Clients: GitOps Pre-Registration via an OAuthClient CRD —
Accepted· 2026-07-28
Policy & Authorization
- Universal Gateway as Policy Enforcement Point —
Accepted· 2026-03-05 - Policy Gateway and Authorisation Model —
Accepted (revised 2026-04-13)· 2026-04-14 - Dynamic Route-Scope Registration —
Accepted (Amended 2026-10-01)· 2026-04-14 - Frontend Policy Projection via BFF —
Accepted· 2026-04-14 - Policy Administration Dashboard —
Accepted (Amended 2026-10-22)· 2026-04-15 - PAT Scope Assignment via Explicit Grants —
Accepted· 2026-04-19 - Gateway-Level OPA Enforcement for External Traffic —
Accepted· 2026-04-27 - Platform-wide Scope Enforcement Middleware —
Accepted· 2026-06-04
Inference Gateway
- Inference Gateway Architecture —
Accepted· 2026-04-01 - Provider Model Catalog and Alias Routing —
Accepted (Amended 2025-07-22)· 2026-04-01 - Anthropic Zero-Translation Path —
Accepted (Amended 2026-10-07)· 2026-04-01 - Model Capability Taxonomy —
Accepted (Amended 2026-10-10)· 2026-04-01 - Virtual Model Catalog and Platform Routing —
Accepted· 2026-04-17 - Inference Usage Logs —
Accepted· 2026-04-17 - Inference Analytics: My Usage and Analytics Tabs —
Accepted (Amended 2026-07-20)· 2026-04-27 - Embeddings and Responses API Endpoints —
Accepted· 2026-05-03 - Inference Log Detail Modal and Failure Details Capture —
Accepted· 2026-06-05 - LLM Cost Tracking: Pricing Pipeline, Budget Enforcement, and Quota Roles —
Accepted (Decision 5 superseded 2026-06-10)· 2026-06-05 - Budget Model Redesign: Inline JSONB on Roles/Grants, MAX Resolution, Per-Category Spend —
Proposed· 2026-06-10 - Budget Enforcement Corrections: Canonical Spend Counter, Request-Time Role Enforcement, All Principal Types, and the Budgets Management Surface —
Proposed· 2026-06-10 - Hierarchical Budget Enforcement: Windows, Pools, Tenant Caps, and Per-Run Limits —
Proposed· 2026-06-10 - Role-Budget Attribution for Non-Interactive Credentials —
Accepted· 2026-06-15 - Model Cost Visibility: Pricing on the Models Page and Virtual Models Catalog —
Accepted· 2026-06-22 - Multi-Account AWS Bedrock Support —
Superseded by [crd-inference-providers](2026-10-01-crd-inference-providers.md)· 2026-06-19 - Provider Error Visibility in the Inference Gateway —
Accepted· 2026-06-19 - Non-Token Model Pricing: Full Cost Dimension Pipeline —
Accepted· 2026-07-24 - CRD-Driven Inference Providers —
Accepted (Amended 2026-10-02)· 2026-10-01 - Decision Models and the System One API —
Accepted· 2026-10-10
Agents Control Plane & Execution
-
Agent Execution Flow Patterns & Delegation —
Accepted· 2026-03-05 -
MCP Server Registration, Deployment, and Governance —
Accepted· 2026-03-05 -
Scope-Gated Tool Exposure via MCP —
Accepted· 2026-03-05 -
Credential-Aware Outbound Gateway —
Superseded· 2026-03-05 -
JIT Credential Brokering via a Per-Tenant Egress Gateway —
Proposed (Amended 2026-10-07: Amendment 5 Accepted)· 2026-06-06 -
Kubernetes Connection —
kubernetesAdapter and Per-Connection Gateway CA Trust —Proposed· 2026-07-06 -
Connection Scope Qualifiers — Grant-Time Resource Scoping for Connectors —
Accepted· 2026-07-22 -
GitHub Connection — Category-Scoped Actions, Repository Qualifiers, and Down-Scoped Token Minting —
Accepted· 2026-07-22 -
GitHub GraphQL Authorised by the Granular Actions of Selected Fields —
Accepted· 2026-09-29 -
Same-Host Connection Selection in the Egress Gateway —
Accepted· 2026-10-15 -
Agent Sandbox Toolchain and Connectivity Environments —
Superseded by [sandbox-environments](2026-10-03-sandbox-environments.md)· 2026-06-14 -
Sandbox Environments —
Accepted (Amended 2026-10-08)· 2026-10-03 -
Bundled Sandbox Images —
Accepted· 2026-10-07 -
Sandbox Workspace Mount —
Accepted· 2026-10-08 -
Agent CLI Framework & Transform Layer —
Accepted· 2026-05-11 -
Codex Agent Runner —
Accepted (Amended 2026-09-29)· 2026-06-04 -
OpenCode Agent Runner —
Accepted (Amended 2026-09-30)· 2026-06-04 -
Agent Registry & Definition Model —
Accepted (Amended 2026-09-29)· 2026-05-11 -
Agent Execution Infrastructure —
Accepted (Amended 2026-10-12)· 2026-05-11 -
kora-agents Service Architecture —
Accepted· 2026-05-11 -
Run & Session Lifecycle —
Accepted (Amended 2026-10-12)· 2026-05-11 -
Run Scheduling —
Accepted· 2026-10-12 -
Per-Run Cost on the Run Record —
Proposed· 2026-10-20 -
Agent Event Streaming Protocol —
Accepted· 2026-05-11 -
Agent Workspace Model —
Accepted· 2026-05-11 -
BYOC Agent Discovery & Observability —
Accepted· 2026-05-11 -
Agent Identity & Policy Provisioning —
Accepted (Amended 2026-09-29)· 2026-05-11 -
Agent Portal & Chat UI —
Accepted· 2026-05-11 -
Sandbox Provisioning and Shell Proxy —
Accepted· 2026-05-11 -
Trace Propagation into the Claude Code Agent Runtime —
Accepted· 2026-09-18 -
Telemetry Collector as a Declared Platform Destination —
Accepted· 2026-09-18 -
Run Activity Events —
Accepted· 2026-09-29 -
kora-agents Route & Scope Registration —
Accepted· 2026-05-11 -
Agents BFF Integration and Run Chat Wiring —
Accepted· 2026-06-04 -
Agent Run Filesystem and Process Isolation —
Accepted (Amended 2026-09-29, 2026-09-30, 2026-10-08)· 2026-06-04 -
Service-Layer Authorization for orbit-agents —
Accepted· 2026-06-04 -
K8s Manifest Field Overrides via Environment Variables —
Superseded by [manifest-patches-configmap](2026-09-15-manifest-patches-configmap.md)· 2026-06-12 -
Config-Driven Kustomize Manifest Patches for orbit-agents —
Accepted· 2026-09-15 -
First-Class Customisation Points for Provisioned Agent Workloads —
Accepted· 2026-09-16 -
Agent Triggers and Webhook Ingestion —
Accepted (Decision item 3 superseded in part 2026-09-29)· 2026-06-17 -
Run Task Summarization —
Accepted· 2026-06-19 -
Extended Trigger Types and an Operable Delivery Pipeline —
Accepted (field map, empty event_type rule and declared event types superseded 2026-09-29)· 2026-06-20 -
Trigger Deliveries: Client-Side Status Filter and Inline Payload Excerpt —
Accepted· 2026-06-20 -
Agent Token Breakdown and Spend Card —
Accepted (Amended 2026-10-06)· 2026-06-23 -
Agent Builder —
Accepted· 2026-07-17 -
Agent Detail Configuration and the Shared Builder Motif —
Accepted· 2026-07-17 -
Motif Component Promotion into Hades —
Accepted· 2026-07-17 -
Alertmanager Webhook Adapter —
Accepted (curated fields and sub-decision 3 superseded in part 2026-09-29)· 2026-07-21 -
Delegated Agent Identity —
Accepted· 2026-07-23 -
Hades Wizard Component —
Proposed· 2026-08-03 -
Owner References for Agents and Sandboxes —
Proposed· 2026-09-06 -
Authenticated Sandbox Exec and Runner Isolation Parity —
Proposed· 2026-09-18 -
Trigger Payload Templating —
Accepted· 2026-09-28 -
Agent Run Guardrails —
Accepted (Amended 2026-09-30)· 2026-09-29 -
Trigger Fire Coalescing —
Accepted· 2026-10-13 -
Trigger Routing —
Accepted· 2026-10-19 -
Chat Command Triggers —
Accepted· 2026-10-20
MCP / Tool Gateway
Build order: Registration is the foundation; the Gateway depends on it, and on OAuth (which can be built in parallel with the Gateway).
- MCP Server Registration & Introspection —
Accepted (Amended 2026-10-22)· 2026-06-29 - MCP / Tool Gateway —
Accepted· 2026-06-29 - MCP OAuth Authentication Model —
Accepted· 2026-06-29 - kora MCP — Platform Management MCP Server —
Accepted· 2026-06-30 - Tenant MCP Servers as a Recognised Workload Class —
Proposed· 2026-09-17 - MCP Server Static Credentials —
Accepted· 2026-10-22
Service Mesh, Operator & Deployment
- Service Mesh and Network Enforcement Infrastructure —
Accepted· 2026-03-05 - Helm Chart Distribution and GitOps Repository Structure —
Accepted· 2026-03-31 - kora Kubernetes Operator —
Superseded· 2026-03-31 - Frontend Cluster Deployment and Ingress Routing —
Accepted· 2026-04-06 - North-South Ingress and External Service Exposure —
Accepted· 2026-07-04 - Install and Distribution Model: Published Charts and a Tenant-Only Operator —
Proposed· 2026-09-04 - Enforcement Sidecar Injection, Preflight and Restricted Pod Security —
Accepted (Amended 2026-10-02, 2026-10-12)· 2026-09-04 - Database Migrations —
Proposed· 2026-09-10 - Agent Pod Egress Lockdown —
Accepted· 2026-09-30
Frontend & Design System
- Frontend Scaffolding and Toolchain —
Accepted· 2026-03-17 - Hades Frontend Design System —
Accepted· 2026-03-25 - Hades Versioning and Theme Surface Manifest —
Accepted· 2026-10-11 - Hades Delivery to External Consumers —
Accepted· 2026-10-11 - White-labelling Theme —
Accepted· 2026-10-12 - Frontend Component Consolidation —
Accepted· 2026-05-04 - Hades Design System Hardening —
Accepted· 2026-05-04 - Semantic HTML Consolidation — Unconditional Ban on header, article, nav, aside, footer —
Accepted· 2026-05-04 - Frontend Test Strategy and Toolchain —
Accepted· 2026-05-08 - Nav Cleanup and Live Dashboard —
Accepted· 2026-06-19 - Mobile & Tablet Responsive Design —
Accepted· 2026-06-19 - Profile Page Architecture —
Proposed· 2026-05-13