Process Roles

The platform is one container image. Every process on the trusted cluster runs that image with a different --role flag, and each role is its own Kubernetes Deployment. This chapter names the roles, describes what each one does, and explains why the split falls where it does.

The image is built from a single TypeScript codebase. The domain lives in src/common: the DAOs, the workflow runner, the model catalog, data sources, billing, auth, the queue contract. Each role is a folder under src/. Its entry file is the process; the folder holds only that role's transport code, and no other role imports from it. In development, the same image runs every role in one process.

#The Roles

The voice worker is a separate image, in services/voice-worker, because its LiveKit bindings need a different base. It registers with the HTTP role and deploys alongside it.

#Why the Split Falls Where It Does

Each role exists for one of three reasons: it holds long-lived connections, it carries rights no request pod should hold, or its lifecycle cannot ride the API's rollout cadence.

Long-lived connections. The WebSocket role and the sandbox proxy role hold hour-long sockets: an editor's control channel, a language server session, a realtime event stream. A rolling deploy of the API tier must not cut these off, and a pod holding one of these sockets must not block the request tier from scaling down. Both roles roll on their own cadence, with their own grace periods.

Rights that request pods must not carry. Two roles talk to a Kubernetes API. The provisioner creates StatefulSets for dedicated retrieval instances on the trusted cluster; the sandbox orchestrator creates pods on the untrusted cluster. Each runs under its own ServiceAccount, scoped to exactly those rights, and the HTTP pods carry none of them. The HTTP role reaches the orchestrator over an internal route with a server token, never with cluster credentials.

Lifecycle. The app database role holds open SQLite connections and flushes them on a debounce, so it drains carefully and hands ownership to a peer on shutdown. The git role holds repositories on local NVMe. The mail inbound role listens on SMTP behind a Network Load Balancer. The provisioner is a singleton, which also makes it the right home for the batch crons that must run exactly once.

Worker pools. The general worker drains queues whose jobs run seconds to minutes: steps, document ingest, file scans, email sends. The bulk worker drains corpus loads, where one batch can saturate a JavaScript thread for minutes at a time. They run on separate node groups, so a bulk load never takes a core from interactive work.

#How Roles Find Each Other

Roles do not import each other. They meet through the data plane and through internal routes.

• Postgres is the shared state. Every role opens the same three pools: writer, reader, and a report reader with a longer timeout.
• Valkey (Redis) carries cache namespaces, pub/sub events for cache invalidation, ownership records for app databases, the warm-pool registry, and the live audit tail.
• SQS (Queue) carries work from the HTTP role to the workers. The message contract lives in src/common/Queue: one module per message type, with its shape, its producer helper, and the handler the worker registers.
• Internal HTTP routes under /_internal connect the HTTP role to the app database, git, and sandbox orchestrator roles. Each is guarded by a server token that never leaves the cluster.
• The callback origin is the one hostname a sandbox reaches back on. Every managed capability an app uses arrives there as a request with a hook token.

#Workload Identity

Every pod runs under an EKS Pod Identity that maps its ServiceAccount to an IAM role with explicit resource ARNs. None of the roles that touch data carry a wildcard.

Worker pods disable the Kubernetes ServiceAccount token mount. Their only identity is the AWS one.