Skip to main content

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 under api/: 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 in config.yml (app.otel_exporter_otlp_endpoint). In production this points to Grafana Alloy. Traces cover HTTP requests, database queries, and worker job processing.