# sumuhridoy2002/ai-mock-interview architecture

> Architecture diagram of the GitHub repository sumuhridoy2002/ai-mock-interview, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sumuhridoy2002/ai-mock-interview
- Repository: https://github.com/sumuhridoy2002/ai-mock-interview

## Overview

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: [`backend/app/Jobs`](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Jobs) (Queue jobs), [`ai-service/app/agents/orchestrator.py`](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/ai-service/app/agents/orchestrator.py) (AI orchestrator), [`backend/app/Services/Interview`](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Services/Interview) (Interview services), [`backend/routes/api.php`](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/routes/api.php) (HTTP API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_fe_app["Next.js app<br/>ui client"]
  node_fe_live["Live interview<br/>session flow<br/>[page.tsx]"]
  node_fe_result["Results view<br/>review flow<br/>[page.tsx]"]
  node_fe_hooks["Media hooks<br/>client hooks"]
  node_fe_api["API client<br/>http client<br/>[api.ts]"]
  node_fe_ws["WebSocket client<br/>realtime client<br/>[websocket.ts]"]
end

subgraph group_backend["Laravel Core"]
  node_be_api["HTTP API<br/>laravel api<br/>[api.php]"]
  node_be_auth["Auth control<br/>controller<br/>[AuthController.php]"]
  node_be_interview["Interview control<br/>controller"]
  node_be_resume["Resume control<br/>controller"]
  node_be_services["Interview services<br/>domain services"]
  node_be_jobs["Queue jobs<br/>async workers"]
  node_be_models[("Interview models<br/>domain model")]
  node_be_events(("Broadcast events<br/>realtime events"))
end

subgraph group_ai["AI Service"]
  node_ai_main["FastAPI app<br/>ai api<br/>[main.py]"]
  node_ai_orch["AI orchestrator<br/>pipeline orchestration<br/>[orchestrator.py]"]
  node_ai_agents["AI agents<br/>llm agents"]
  node_ai_pipelines["Media pipelines<br/>speech vision"]
  node_ai_ollama["Ollama client<br/>llm runtime<br/>[ollama_client.py]"]
  node_ai_fallback["Heuristic fallback<br/>offline logic"]
end

subgraph group_infra["Infrastructure"]
  node_db[("Database<br/>mysql postgres")]
  node_redis[("Redis<br/>cache queue<br/>[queue.php]")]
  node_storage[("File storage<br/>artifact store")]
  node_reverb(("Reverb<br/>websocket server<br/>[reverb.php]"))
  node_mail["Email delivery<br/>smtp mail<br/>[mail.php]"]
end

node_fe_app -->|"HTTP calls"| node_fe_api
node_fe_app -->|"subscribe"| node_fe_ws
node_fe_live -->|"uses"| node_fe_hooks
node_fe_result -->|"loads results"| node_fe_api
node_be_api -->|"routes"| node_be_auth
node_be_api -->|"routes"| node_be_interview
node_be_api -->|"routes"| node_be_resume
node_be_auth -->|"persists users"| node_be_models
node_be_resume -->|"parses resume"| node_be_services
node_be_interview -->|"orchestrates"| node_be_services
node_be_services -->|"dispatches"| node_be_jobs
node_be_jobs -->|"calls AI"| node_ai_main
node_be_services -->|"stores domain"| node_be_models
node_be_jobs -->|"write results"| node_db
node_be_models -->|"mapped to"| node_db
node_be_jobs -->|"read/write files"| node_storage
node_be_jobs -->|"queue via"| node_redis
node_be_events -->|"broadcasts"| node_reverb
node_be_interview -->|"emits"| node_be_events
node_be_jobs -->|"send email"| node_mail
node_ai_main -->|"orchestrates"| node_ai_orch
node_ai_orch -->|"delegates"| node_ai_agents
node_ai_orch -->|"transcribes"| node_ai_pipelines
node_ai_orch -->|"llm calls"| node_ai_ollama
node_ai_orch -->|"fallback"| node_ai_fallback
node_ai_agents -->|"analyze data"| node_db
node_fe_ws -->|"connects to"| node_reverb

click node_fe_app "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/frontend/app"
click node_fe_live "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/frontend/app/interview/live/[sessionId]/page.tsx"
click node_fe_result "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/frontend/app/interview/result/[id]/page.tsx"
click node_fe_hooks "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/frontend/hooks"
click node_fe_api "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/frontend/lib/api.ts"
click node_fe_ws "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/frontend/lib/websocket.ts"
click node_be_api "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/routes/api.php"
click node_be_auth "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/app/Http/Controllers/Api/AuthController.php"
click node_be_interview "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/app/Http/Controllers/Api/InterviewController.php"
click node_be_resume "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/app/Http/Controllers/Api/ResumeController.php"
click node_be_services "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Services/Interview"
click node_be_jobs "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Jobs"
click node_be_models "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Models"
click node_be_events "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Events"
click node_ai_main "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/ai-service/app/main.py"
click node_ai_orch "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/ai-service/app/agents/orchestrator.py"
click node_ai_agents "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/ai-service/app/agents"
click node_ai_pipelines "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/ai-service/app/pipelines"
click node_ai_ollama "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/ai-service/app/services/ollama_client.py"
click node_ai_fallback "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/ai-service/app/services/heuristic_evaluator.py"
click node_db "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/database"
click node_redis "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/config/queue.php"
click node_storage "https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/storage/app"
click node_reverb "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/config/reverb.php"
click node_mail "https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/config/mail.php"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_fe_app,node_fe_live,node_fe_result,node_fe_hooks,node_fe_api,node_fe_ws toneBlue
class node_be_api,node_be_auth,node_be_interview,node_be_resume,node_be_services,node_be_jobs,node_be_models,node_be_events toneAmber
class node_ai_main,node_ai_orch,node_ai_agents,node_ai_pipelines,node_ai_ollama,node_ai_fallback toneMint
class node_db,node_redis,node_storage,node_reverb,node_mail toneRose
```

## Components

### Frontend

Next.js client for auth, setup, live interview, and results review.

- [Next.js app](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/frontend/app): ui client · User-facing presentation layer for the interview platform. · `frontend/app`
- [Live interview](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/frontend/app/interview/live/[sessionId]/page.tsx): session flow · Client-side live interview experience with recording and session sync. · `frontend/app/interview/live/[sessionId]/page.tsx`
- [Results view](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/frontend/app/interview/result/[id]/page.tsx): review flow · Interview result and question review screens. · `frontend/app/interview/result/[id]/page.tsx`
- [Media hooks](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/frontend/hooks): client hooks · Recording, alarms, session, websocket, and metrics hooks. · `frontend/hooks`
- [API client](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/frontend/lib/api.ts): http client · Typed frontend access to backend HTTP endpoints. · `frontend/lib/api.ts`
- [WebSocket client](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/frontend/lib/websocket.ts): realtime 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](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/routes/api.php): laravel api · Authentication, resume, interview, and answer endpoints. · `backend/routes/api.php`
- [Auth control](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/app/Http/Controllers/Api/AuthController.php): controller · Login, registration, and token/session handling. · `backend/app/Http/Controllers/Api/AuthController.php`
- [Interview control](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/app/Http/Controllers/Api/InterviewController.php): controller · Interview setup, live flow, and result retrieval. · `backend/app/Http/Controllers/Api/InterviewController.php`
- [Resume control](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/app/Http/Controllers/Api/ResumeController.php): controller · Resume upload and resume lifecycle endpoints. · `backend/app/Http/Controllers/Api/ResumeController.php`
- [Interview services](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Services/Interview): domain services · Core orchestration for interview logic, scoring, memory, and reports. · `backend/app/Services/Interview`
- [Queue jobs](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Jobs): async workers · Background work for parsing, generation, evaluation, analysis, and reporting. · `backend/app/Jobs`
- [Interview models](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Models): domain model · Users, resumes, interviews, answers, scores, reports, sessions, and memory. · `backend/app/Models`
- [Broadcast events](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/app/Events): realtime 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](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/ai-service/app/main.py): ai api · Python AI service entrypoint for interview intelligence. · `ai-service/app/main.py`
- [AI orchestrator](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/ai-service/app/agents/orchestrator.py): pipeline orchestration · Coordinates specialized AI agents and fallbacks. · `ai-service/app/agents/orchestrator.py`
- [AI agents](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/ai-service/app/agents): llm agents · Question generation, evaluation, explanations, job analysis, memory, and reporting. · `ai-service/app/agents`
- [Media pipelines](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/ai-service/app/pipelines): speech vision · Transcription and other media-processing pipelines. · `ai-service/app/pipelines`
- [Ollama client](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/ai-service/app/services/ollama_client.py): llm runtime · Adapter for local LLM reasoning and generation. · `ai-service/app/services/ollama_client.py`
- [Heuristic fallback](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/ai-service/app/services/heuristic_evaluator.py): offline logic · Deterministic evaluation path when model-backed reasoning is unavailable. · `ai-service/app/services/heuristic_evaluator.py`

### Infrastructure

Shared runtime dependencies and delivery channels.

- [Database](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/database): mysql postgres · Primary persistence for users, interviews, answers, reports, and memory. · `backend/database`
- [Redis](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/config/queue.php): cache queue · Queueing, cache, and coordination layer for Laravel runtime. · `backend/config/queue.php`
- [File storage](https://github.com/sumuhridoy2002/ai-mock-interview/tree/master/backend/storage/app): artifact store · Uploaded resumes, transcripts, and interview artifacts. · `backend/storage/app`
- [Reverb](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/config/reverb.php): websocket server · Laravel websocket server for live interview broadcasting. · `backend/config/reverb.php`
- [Email delivery](https://github.com/sumuhridoy2002/ai-mock-interview/blob/master/backend/config/mail.php): smtp mail · Welcome and reminder notifications sent from Laravel. · `backend/config/mail.php`

## Connections

- 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.