docs/ARCHITECTURE.md

Architecture

System overview

Speech-Machine runs as a Next.js web app, a FastAPI API, PostgreSQL, Redis, and an arq worker.

Browser -> Next.js web -> FastAPI API -> PostgreSQL
                              |
                              v
                            Redis -> arq worker -> ffmpeg/faster-whisper
                              |
                              v
                         local or S3 storage

Request lifecycle

1. The browser records or uploads a video and creates a session through the API.
2. The API validates file size and magic bytes, stores the video, and marks transcription as queued.
3. The API enqueues transcribe_recording in Redis and returns a job_id.
4. The worker extracts audio, transcribes it, stores transcript segments, recomputes score data, and marks the session complete or failed.
5. The frontend polls the session and can also poll /jobs/{job_id} for background job state.

Security boundaries

• First-run setup creates the admin account; there are no default admin/admin credentials.
• Access tokens are short-lived and stored in memory. Refresh tokens are HttpOnly cookies and are rotated on use.
• CORS is allowlisted through CORS_ORIGINS.
• Uploads are bounded by MAX_UPLOAD_MB and validated by content signature.
• Docker runs Alembic migrations before the API starts.