Repo Map
The platform is six repositories: one web app, one embedded session room, three backend services, and one end-to-end test suite. Each paragraph below is the one-minute orientation; the linked page is the deep dive.
interviews-ui — the web app
The Next.js 15 (React, TypeScript) application every user sees at https://www.theinterviews.ai: marketing pages, candidate and recruiter dashboards, plan selection and Stripe checkout, the Profile Card, resume tools, and the entry point into every interview. It talks to the platform over three strictly separated data paths — REST+JWT to user-management via typed service clients (all user/billing/meeting data), a thin set of Next.js serverless routes used only for OpenAI calls (so the key stays server-side), and a WebSocket connection to the LiveKit SFU for real-time audio/video. Plan and entitlement checks go through a single shared utility rather than scattered plan-name string checks. Deep dive: interviews-ui architecture.
smart-interview-ui — the live session room
A plain React SPA (Create React App, JavaScript — deliberately not Next.js) that renders the live interview room. It is not a standalone site: interviews-ui embeds it in an iframe and hands it the session ID via query parameters or origin-validated postMessage; user-management remains the authority for that ID. The room fetches its LiveKit access token from video-streaming-server (tokens are never minted in the browser), connects to the SFU over WebSocket, and attaches a correlation header on its server calls so a session can be traced across services. Because every one of its build-time variables is baked into the public bundle, this app ships zero secrets by design. Deep dive: smart-interview-ui architecture.
video-streaming-server — the media, session, and recording service
A single Node.js (ESM, Express + socket.io) process that owns the real-time plumbing of a live AI interview: LiveKit access-token issuance, recording orchestration (egress to <S3_BUCKET>, finalize/merge, webhooks, Redis-backed state), neural text-to-speech for the interviewer's voice, a streaming speech-to-text WebSocket proxy, and short-lived session-token minting for the Simli/Spatius avatars — all so third-party API keys never reach the browser. It also still hosts a legacy in-process AI brain (question generation, evaluation, feedback) that is being retired under the TI-340 migration waves: net-new AI logic belongs in bot-backend, and this repo accepts bug fixes and migration-shim work only. Deep dive: video-streaming-server architecture.
bot-backend — the AI interview worker (the current brain)
The AI interview brain in the current workflow: a Python 3.13 service combining a FastAPI app (question planning and evaluation endpoints, plus health/metrics) with a livekit-agents worker that joins LiveKit rooms as a participant to transcribe and summarize. It powers production AI-bot interviews, including the blended technical interview format. The voice-loop capabilities — LLM, speech-to-text, text-to-speech, avatar — are modeled as swappable interfaces, with the remaining providers wired in per TI-340 migration wave. It holds no database connection of its own: results are POSTed to user-management's internal API using a short-lived service JWT and idempotency keys. Deep dive: bot-backend architecture.
user-management — the core backend
The stateless Java 21 / Spring Boot REST API that is the source of truth for everything account-shaped: authentication (user JWTs, Google OAuth, magic links), customers, subscription plans, billing and Stripe webhooks, plan/usage enforcement (consuming interview and feedback quota), the job-description funnel, and Profile Card data. It follows a strict thin-controller → service → repository layering on PostgreSQL, exposes a JWT-gated internal API for service-to-service writes from bot-backend and video-streaming-server, and hosts the AI-routing filter that flips per-surface AI traffic onto bot-backend as the TI-340 migration waves graduate. Deep dive: user-management architecture.
theinterviews-e2e — the end-to-end test suite
The Playwright harness that tests deployed environments rather than shipping any app code. It is tiered: free read-only smoke checks against production, browserless REST contract tests against user-management, authenticated UI checks, and a live AI tier that drives a real candidate journey — a controllable fake microphone injects pre-recorded WAV answers on cue, so speech-to-text, endpointing, and turn-taking run for real (and cost real AI minutes, so that tier is run deliberately, never casually). Deep dive: E2E suite.