Architecture
System architecture
Runtime topology — apps, core-api, satellite services, data plane, and the only path to OpenAI.
Owner: Platform EngineeringLast reviewed:
Everything user-facing is a Next.js App Router app acting as a BFF: the browser
talks only to its app, the app attaches a short-lived access token server-side
and calls core-api. Durable async work (transcription assembly, generation,
rendering, delivery, retention) is queued on NATS JetStream and executed by the
worker service. AI traffic has exactly one egress point: ai-gateway.
How to read this diagram
- Browser → app → core-api. No browser ever calls
core-api, holds a token, or reaches the data plane. Sessions are encrypted HttpOnly cookies (ADR 0003). - core-api owns the data plane. It is the only writer of domain state: PostgreSQL (with row-level security, ADR 0004), Redis for cache and rate limits only (ADR 0006), NATS JetStream for durable events (ADR 0005), and MinIO for tenant-prefixed objects (ADR 0007).
- worker consumes, never invents. It picks up
recording.finalized,ai_generation.requested,document.approved, and similar events, and callsai-gatewayordocument-serviceas needed — always with idempotency keys. - ai-gateway is the single OpenAI path. It applies the
AI_PHI_MODEprivacy gate, de-identification, pinned model routing, structured outputs, and cost accounting (ADR 0011). It is not reachable from browsers. - realtime-gateway bridges NATS events (recording, transcription, job and island state) to authenticated WebSockets; it persists nothing.
For service responsibilities, trust boundaries, sequence diagrams of the recording → transcript → draft → approval flow, and degraded modes, see the system overview.