Architecture and components
Cortex is a set of cooperating services running as containers on one Kubernetes cluster, in two environments. The applications it generates for a customer are not part of this architecture; see Independent applications and Applications.
Three planes
Each plane runs in its own containers and talks to the others over HTTP.
| Plane | Contains | Owns |
|---|---|---|
| Control plane | The API and access control, the web application, and the assistant (an MCP server exposing the typed tools and hosting the in-product chat) | Every project's configuration. Recipe configuration in the versioned configuration store; platform state in the platform database |
| Engine plane | The execution engine. Every project has a paired fork: a catalogue of endpoints (flow graphs) and services (containers) | Pipelines, business workflows, model training, knowledge-base indexing and every data operation an app calls. One image runs as studio, RPC server, endpoint runtime, service manager and exporter |
| Runtime plane | The generated applications: app services (a container definition plus source tree, built in-cluster, run as its own deployment at its own hostname), function services and governed target databases | The customer's application and its data. Cortex frames these applications and does not render them |
Components by responsibility
| Component | Responsibility | State it owns | How it runs |
|---|---|---|---|
| API and access control | REST API, authentication, one shared fail-closed access policy, project registry, recipe and platform-state reads and writes, job queue and schedules, a thin proxy to engine operations. No business logic, no file parsing, no dispatch on source kind | Recipe writes as commits; the platform database | One deployment, non-root |
| Web application | The single-page UI, the pipeline and workflow canvases, the embedded studio | Browser state only | Static assets behind a lightweight web server |
| Assistant | The typed tools over MCP (Streamable HTTP, OAuth 2.1), the chat and the orchestrator, the persona services on loopback so delegation stays inside the process boundary | OAuth grants, chat sessions | One deployment, non-root, read-only root filesystem |
| Persona services | The engine persona (read-only recipe tools plus the paired fork's MCP, for authoring endpoints and services) and the analyst persona (the project's analytics endpoints only) | None | Their own deployments, also mounted inside the assistant on loopback |
| Account service | Issues and refreshes sessions for the platform and deployed applications; signs tokens with a private key only it holds | Account rows | One deployment |
| Agent fleet | Workers that claim cards from every project queue and run each in an isolated coding-agent session with a leased model credential | None | A separate deployment on a dedicated node; not restarted by a platform deploy |
| Transcription service | Turns uploaded audio requirement sources into text | None | One deployment |
| Engine: studio | Visual editor of forks, endpoints and services, embedded for platform staff | Engine catalogue | Part of the engine image |
| Engine: RPC | The engine's command surface for the API, the studio and the MCP tools | Engine catalogue | Part of the engine image |
| Engine: endpoint runtime | Executes flow graphs with the project's environment injected | Run-time state in the in-memory cache | Part of the engine image |
| Engine: service manager | Builds and runs function services and app services; a compose adapter for a single host and a Kubernetes adapter for the cluster | Service definitions in the engine catalogue | Its own deployment |
| Engine: exporter | Produces the git export, the local-run bundle, the customer archive and the delivery contents | Export configuration in the engine catalogue | Its own deployment |
| Shared test runner | Executes requirement-linked tests identically inside cortex, inside every customer archive and on any machine | Results stored by the API | A child process of the API; a container inside archives |
| Function services | Small handlers a project owns, plus the shared services on the prototype fork: the record pipeline, the machine-learning service, the knowledge-base service | Project data | Built in-cluster, one deployment per service |
Report PDFs come from a document renderer fed a generated manifest. Guide PDFs and screenshots come from a headless browser.
Stores by role
| Store | What it holds | Guarantees |
|---|---|---|
| Versioned configuration store | One database per project: sources, targets, data elements, mappings, processing rules, pipeline nodes and links, reference lists, access policies | Every write a commit attributed to the caller; branchable and mergeable |
| Platform database | Users, organisations, projects, roles, the app registry, the requirements chain, tests and health verdicts, job queues, fleet sessions | Written by the API only; audit log and a timeline per project |
| Governed target databases | Pipeline output per project, workflow tables, app data | Apps read them through guarded endpoints, never from the browser |
| Vector index | Knowledge-base indexes, one schema per knowledge-base source | Shared database, per-source isolation |
| Engine catalogue | Forks, endpoints, services, app services, export configuration, knowledge pages | Engine only; endpoint history versioned; exported to git |
| In-memory cache | Studio fan-out, dispatch, engine caches | Ephemeral |
| Object storage | Uploads, requirement source originals, knowledge-base documents, generated reports, export bundles | S3-compatible; one prefix per project or the organisation's own bucket |
Model access
Three routes reach a model over the same code paths, chosen per environment.
| Route | How it is wired | Where it is used |
|---|---|---|
| The cloud provider's model service | A gateway inside the assistant maps model names to the provider's models; credentials come from the pod's identity role, so no key is stored | Production default for the chat and the persona sub-agents |
| An API-compatible gateway | The same gateway exposes a standard chat-completion protocol | One gateway in front of several vendors |
| A vendor API | The vendor's own API or a subscription credential | Development environments and local stands |
The agent fleet drives coding-agent sessions and calls no model API itself; the coding agent is pluggable and each lane's model is a registry row. Externally reachable MCP surfaces require OAuth 2.1 bearer tokens with PKCE, so any MCP client calls the same typed tools the UI uses.
Hosting model
| Concern | How it is done |
|---|---|
| Compute | One Kubernetes cluster on AWS; one namespace per environment (production and development, each from its own branch); the fleet pinned to a dedicated node |
| Images | A private container registry in the hosting cloud, one repository per platform image |
| In-cluster builds | Project-owned images built inside the cluster by an in-cluster image builder; a failed build job fails the build |
| Ingress | A load balancer with managed certificates; app services get one ingress each in a shared group, at their own hostname under the environment's apps domain or at a customer-supplied domain |
| Certificates and DNS | Wildcard certificates per apps domain; each environment also answers on a second domain through extra host rules on the same load balancers |
| Infrastructure as code | Every change is an edit to declarative definitions in an operations repository, then an apply; no manual edits in the cluster or the cloud console |
| Other cloud services | Object storage, transactional email, the model service, identity roles for workloads, static sites behind a content delivery network |
| Observability | Metrics endpoints on the engine; health transitions post to Slack; a test watchdog runs every project's suite every 15 minutes |
| Local development | A container-compose stand with the stores and the engine; the API, the assistant and the web application on the host |
CI/CD
On every push to the development and production branches the pipeline runs three stages. Verify: unit tests of the engine, the account service and the API, a dependency audit that fails on critical advisories, a secret-hygiene scan. Build: every platform image in parallel, pushed to the registry tagged with commit and branch. Roll: a rolling restart of every deployment that consumes a rebuilt image; the fleet rolls separately so running jobs finish.
After a deploy the platform re-runs every project's test suite. Promotion of a project copy between environments ends with a test gate that refuses a red target. Each fork has a private git repository to which the exporter pushes its endpoints, services and app services as ordinary source.
Security posture summary
| Control | Implementation |
|---|---|
| Container hardening | Non-root users in every image; read-only root filesystems in the cluster |
| Authentication | Signed bearer tokens from the account service; OpenID Connect single sign-on; OAuth 2.1 with PKCE on every externally reachable MCP surface; loopback-only MCP surfaces carry no token |
| Authorisation | One shared access policy, fail closed. Project shares open exactly the route surface of the shared app and its enabled companions |
| Secrets | Per-project secrets injected from the project's own environment; platform secrets never mounted into a project-owned container; model access through identity roles; customer archives mint their own credentials |
| Audit trail | Every configuration write a commit attributed to the caller; an audit log and a timeline per project |
| Network | Project services reach each other by cluster DNS; an app service must opt in to a public ingress |
| Supply chain | Dependency audit and secret scan before every image build; pinned coding-agent versions |
| Compliance | SOC 2 readiness programme with an automated evidence register per project. Trust center: trust.tiva-ai.com |
See Security and operations for the operating model behind these controls.
In development: a compiled single-process distribution
A compiled single-process distribution serves the API, the engine, the account service and the MCP surface from one binary against the same stores. It runs on a separate stand with a live parity suite against the current engine. It is not the production runtime, and nothing on these pages depends on which distribution serves the platform.