Edges
app/api/v1
Public REST API.
app/api/internal
HMAC-protected connector callbacks.
app/realtime
Socket.IO server and typed emitters.
Developer guide
¶ Backend Guide
The backend lives in apps/api and is the source of truth for REST, Socket.IO, queue production, tenancy, persistence, and internal HMAC callbacks.
apps/api
Source of truth
ruff · mypy · pytest
Key areas
¶ Where code lives inside apps/api
Requests enter at the edges, business logic sits in services, and shared infrastructure handles queues and security.
Core
app/services
Business logic.
app/models
SQLAlchemy ORM.
app/schemas
Pydantic I/O.
Infrastructure
app/queue
BullMQ producer and API-side workers.
app/security
Hashing, JWT, HMAC, and cookies.
Transcripts and translation
¶ Rules that must stay aligned
Each rule has a second place in the code that has to agree with it. Change both together.
¶ Background enqueue is voice notes only
media_fetch.maybe_enqueue_enrichment only enqueues audio with the PTT/voice_note flag.
Keep aligned with the worker gates.
¶ UI-initiated transcripts can transcribe any audio
Worker enrichment supports an on-demand mode for transcripts the user asks for from the UI.
The worker must carry the same
on_demand flag through its checks.¶ Tenant-scoped, with an allowed target list
The server exposes a tenant-scoped translate endpoint. The client translate helper handles trimming and user-facing errors.
The API target list must match the frontend
TRANSLATE_TARGETS.cd apps/api
ruff check .
mypy app
pytest