Services
Who talks to what
A job’s life: the API commits a job row to Postgres, publishes the job to RabbitMQ and returns. A worker takes delivery, claims the row with an atomic
UPDATE, does the work, writes the result to Postgres, acknowledges the message, and publishes a status change on Redis so the UI updates. The API reconciler republishes anything the broker could not recover.
Encryption and network isolation
Every connection between services is encrypted in transit, and the data stores are never exposed to the internet. Only the web app and API sit behind the public reverse proxy; everything else is reachable solely over a private VPN.Encrypted connections
Certificates are verified on every connection; there is no plaintext fallback in staging or production. Local development (
app.env: development) is exempt so a laptop does not need certificates.
Encrypted at rest
Objects in S3 are encrypted with SSE-C: the API and workers send a platform key with each request, so the storage provider never holds it. Audio is served to browsers through the API (signed, expiring links), not presigned storage URLs. See Configuration.Private network only
PostgreSQL, RabbitMQ, Redis and Neo4j carry no public address and have no ports open to the internet. The API and workers reach them over Tailscale, which keeps the path between each service and its data store as direct as possible, with no hop through a public network. Developer machines cannot connect to a data store directly either — access goes through the API. TLS and Tailscale are separate layers. Traffic is encrypted end to end by the protocols above, and Tailscale (with an ACL that admits only the application and GPU hosts, see Deployment) means the ports they run on are not reachable from outside in the first place. Neither depends on the other.Startup validation
The API and every worker check their connection URLs at boot (kair_voice_core::transport_security) and flag any that are not encrypted. Which rules apply, and whether a violation is logged or stops startup, is described in Configuration. The per-key requirements are listed under Deployment.
Codebase layout
The backend is a Rust Cargo workspace underapi/:
The frontend is a SvelteKit app under
ui/web/.
Authentication model
Two token types are in use:
Guest users get short-lived JWT tokens scoped to a single session.
WebSocket
Each browser tab keeps one WebSocket (/api/realtime) and subscribes to topics. Producers publish invalidation events to the kair:realtime Redis channel, every API replica forwards them to its own sockets, and the client refetches over REST. Nothing polls for recording status, live sources, job state or devices. See Realtime.
Observability
The API and workers export OpenTelemetry traces over OTLP (HTTP/protobuf) to whatever collector is configured inconfig.yml (app.otel_exporter_otlp_endpoint). In production this points to Grafana Alloy. Traces cover HTTP requests, database queries, and worker job processing.