How sumuhridoy2002/ai-mock-interview works
1. Overall shape
- This is a three-tier mock interview platform:
- Next.js frontend for the user experience.
- Laravel backend as the system of record and orchestration layer.
- Python FastAPI AI service for transcription and LLM-driven interview intelligence.
2. Frontend boundary
- The frontend/ app is the presentation layer for authentication, resume upload, interview setup, live interview, and results review.
- It talks to the Laravel API over HTTP and to Laravel Reverb over WebSockets for real-time interview interaction.
- It does not own business logic; it renders views and drives client-side recording/session flows.
3. Laravel API as the orchestration core
- The backend/ app owns users, resumes, interviews, questions, answers, scores, reports, and memory profiles.
- Controllers accept requests, services encapsulate interview logic, and jobs push expensive or asynchronous work off the request path.
- This is the main boundary where AI results are persisted, normalized, and attached to interview records.
4. AI service boundary
- The ai-service/ is a separate Python service dedicated to AI workloads that are too slow or specialized for PHP.
- It combines Whisper for speech-to-text and Ollama for LLM reasoning, question generation, evaluation, and report-style outputs.
- It also includes heuristic/offline fallbacks, so core flows can still run when Ollama is unavailable.
5. End-to-end interview data flow
- A user uploads a resume in the frontend.
- Laravel stores the file and dispatches a resume parsing job.
- Parsed resume data and user context are used later to generate interview questions, evaluate answers, and build reports.
- The interview session then progresses through live questions, answers, transcription, scoring, and post-session reporting.
6. Async processing and background workers
- The backend relies heavily on queue jobs for AI-related steps:
- resume parsing
- job description analysis
- question generation
- answer evaluation
- behavioral analysis
- report generation
- reminder emails
- This keeps the web API responsive while long-running AI and document tasks complete in the background.
7. Real-time interview delivery
- Laravel Reverb is used as the WebSocket layer for live interview interactions.
- Events like QuestionGenerated, AnswerEvaluated, and InterviewCompleted indicate the app broadcasts state changes to connected clients.
- The frontend listens for these updates to keep the live interview experience synchronized without polling.
8. Persistence and domain model
- The backend database stores the interview domain as separate entities:
- users and authentication tokens
- resumes
- interviews and sessions
- interview questions and answers
- scores and reports
- agent memories and mastery profiles
- answer behaviors
- This suggests the system tracks both per-interview outputs and longer-term personalization data.
9. Memory and personalization layer
- Several models and services indicate the platform remembers prior performance:
- AgentMemory
- UserMemoryProfile
- UserQuestionMastery
- AnswerBehavior
- These are used to adapt future interviews, explain weak answers, and generate more targeted follow-up questions.
10. File and media handling
- The backend stores uploaded resumes and interview artifacts under Laravel storage.
- The frontend includes media recording hooks, implying audio/video capture is part of the interview flow.
- The backend also has transcript cleaning and recording-related request validation, showing that recorded media is processed before evaluation.
11. Scheduled notifications
- The backend scheduler sends interview reminders ahead of scheduled sessions.
- Email templates exist for welcome and reminder messages, and reminder delivery is also represented as queue jobs.
- This makes time-based communication a first-class subsystem rather than a frontend responsibility.
12. Infrastructure and runtime split
- The repo expects multiple cooperating processes in development and production:
- Laravel API
- Laravel queue worker
- Laravel scheduler
- Reverb WebSocket server
- FastAPI AI service
- Ollama model server
- Redis is used for queueing, cache/session behavior, and coordination, making it a core infrastructure dependency.
13. Testing and verification
- The frontend includes Playwright end-to-end journeys that validate the full user path from registration to interview completion and reminders.
- The backend has feature/unit tests focused on API behavior and notifications.
- The AI service includes sample CV data, implying isolated validation of parsing and generation logic.
14. Architecture summary for a diagram
- Draw the frontend as the user-facing client.
- Place Laravel in the center as the orchestration and persistence layer.
- Show the AI service as an external intelligence engine called by Laravel jobs/services.
- Add Redis, database, storage, email, and WebSocket broadcast channels as shared infrastructure around the backend.
- The key flow is: user action → Laravel API → async job/AI service → persisted result → realtime update/email/report back to user.
Main entry points: Jobs Queue jobs · orchestrator.py AI orchestrator · Interview Interview services · api.php HTTP API
Components 25
Frontend
Next.js client for auth, setup, live interview, and results review.
- Next.js app · User-facing presentation layer for the interview platform.
frontend/app - Live interview · Client-side live interview experience with recording and session sync.
frontend/app/interview/live/[sessionId]/page.tsx - Results view · Interview result and question review screens.
frontend/app/interview/result/[id]/page.tsx - Media hooks · Recording, alarms, session, websocket, and metrics hooks.
frontend/hooks - API client · Typed frontend access to backend HTTP endpoints.
frontend/lib/api.ts - WebSocket client · Frontend websocket connection used to receive interview updates.
frontend/lib/websocket.ts
Laravel Core
API, domain orchestration, persistence, queues, and realtime events.
- HTTP API · Authentication, resume, interview, and answer endpoints.
backend/routes/api.php - Auth control · Login, registration, and token/session handling.
backend/app/Http/Controllers/Api/AuthController.php - Interview control · Interview setup, live flow, and result retrieval.
backend/app/Http/Controllers/Api/InterviewController.php - Resume control · Resume upload and resume lifecycle endpoints.
backend/app/Http/Controllers/Api/ResumeController.php - Interview services · Core orchestration for interview logic, scoring, memory, and reports.
backend/app/Services/Interview - Queue jobs · Background work for parsing, generation, evaluation, analysis, and reporting.
backend/app/Jobs - Interview models · Users, resumes, interviews, answers, scores, reports, sessions, and memory.
backend/app/Models - Broadcast events · State-change events such as question generation, answer evaluation, and completion.
backend/app/Events
AI Service
FastAPI service for transcription, parsing, generation, evaluation, and reporting.
- FastAPI app · Python AI service entrypoint for interview intelligence.
ai-service/app/main.py - AI orchestrator · Coordinates specialized AI agents and fallbacks.
ai-service/app/agents/orchestrator.py - AI agents · Question generation, evaluation, explanations, job analysis, memory, and reporting.
ai-service/app/agents - Media pipelines · Transcription and other media-processing pipelines.
ai-service/app/pipelines - Ollama client · Adapter for local LLM reasoning and generation.
ai-service/app/services/ollama_client.py - Heuristic fallback · Deterministic evaluation path when model-backed reasoning is unavailable.
ai-service/app/services/heuristic_evaluator.py
Infrastructure
Shared runtime dependencies and delivery channels.
- Database · Primary persistence for users, interviews, answers, reports, and memory.
backend/database - Redis · Queueing, cache, and coordination layer for Laravel runtime.
backend/config/queue.php - File storage · Uploaded resumes, transcripts, and interview artifacts.
backend/storage/app - Reverb · Laravel websocket server for live interview broadcasting.
backend/config/reverb.php - Email delivery · Welcome and reminder notifications sent from Laravel.
backend/config/mail.php
Connections 27
- Next.js app → API client: HTTP calls · Frontend drives auth, setup, upload, and result retrieval through the API client.
- Next.js app → WebSocket client: subscribe · Frontend listens for live interview updates over websockets.
- Live interview → Media hooks: uses · Live interview page uses recording, session, and alarm hooks.
- Results view → API client: loads results · Results pages fetch interview reports and question detail data.
- HTTP API → Auth control: routes · API routes dispatch authentication requests to the auth controller.
- HTTP API → Interview control: routes · API routes dispatch interview lifecycle requests.
- HTTP API → Resume control: routes · API routes dispatch resume upload and management requests.
- Auth control → Interview models: persists users · Authentication reads and writes user state through the domain models.
- Resume control → Interview services: parses resume · Resume upload triggers resume-oriented domain services.
- Interview control → Interview services: orchestrates · Interview controller delegates business logic to interview services.
- Interview services → Queue jobs: dispatches · Long-running AI and document tasks are offloaded to background jobs.
- Queue jobs → FastAPI app: calls AI · Jobs invoke the Python AI service for transcription and LLM work.
- Interview services → Interview models: stores domain · Services normalize and persist interviews, answers, scores, reports, and memory.
- Queue jobs → Database: write results · Background work persists parsed, evaluated, and generated outputs.
- Interview models → Database: mapped to · Domain entities are backed by the primary database.
- Queue jobs → File storage: read/write files · Jobs consume uploaded resumes and store generated artifacts.
- Queue jobs → Redis: queue via · Async work is scheduled and processed through Redis-backed queues.
- Broadcast events → Reverb: broadcasts · Interview state changes are published over Reverb.
- Interview control → Broadcast events: emits · Interview flows emit question, evaluation, and completion events.
- Queue jobs → Email delivery: send email · Reminder and welcome jobs deliver email notifications.
- FastAPI app → AI orchestrator: orchestrates · FastAPI entrypoint routes requests into the AI orchestrator.
- AI orchestrator → AI agents: delegates · The orchestrator selects specialized agents for generation, evaluation, and reporting.
- AI orchestrator → Media pipelines: transcribes · Media pipelines handle audio and transcript processing.
- AI orchestrator → Ollama client: llm calls · Model-backed reasoning and generation go through the Ollama client.
- AI orchestrator → Heuristic fallback: fallback · Heuristic evaluation is used when LLM services are unavailable.
- AI agents → Database: analyze data · AI-derived outputs are ultimately normalized into persisted interview data.
- WebSocket client → Reverb: connects to · Frontend websocket client connects to the Reverb server.