# zendacross97/ai-interview-coach architecture

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

- Interactive diagram: https://gitdiagram.com/zendacross97/ai-interview-coach
- Repository: https://github.com/zendacross97/ai-interview-coach

## Overview

AI Interview Coach serves candidates through account and payment flows into resume-backed, real-time AI interviews, then stores completed transcripts and scorecards for review. The map follows documented capabilities and the sampled controller, WebSocket, service, and model calls. Some routes and integrations are represented from README or index references; unsampled implementation details and their wiring are not inferred.

Main entry points: [`services/interviewService.js`](https://github.com/zendacross97/ai-interview-coach/blob/main/services/interviewService.js) (Session & scorecards), [`controllers/interviewController.js`](https://github.com/zendacross97/ai-interview-coach/blob/main/controllers/interviewController.js) (Interview APIs), [`ws/handler.js`](https://github.com/zendacross97/ai-interview-coach/blob/main/ws/handler.js) (Live interview handler), [`services/resumeService.js`](https://github.com/zendacross97/ai-interview-coach/blob/main/services/resumeService.js) (Resume ingestion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_access["Accounts &amp; access"]
  node_app["HTTP server<br/>[app.js]"]
  node_user_routes["Account routes<br/>[userRoutes.js]"]
  node_user_controller["Account workflows<br/>[userController.js]"]
  node_auth["JWT authentication<br/>[auth.js]"]
  node_payment_routes["Payment routes<br/>[paymentRoute.js]"]
  node_payment_controller["Payment workflow"]
end

subgraph group_interviews["Interview experience"]
  node_interview_routes["Interview routes<br/>[interviewRoute.js]"]
  node_interview_controller["Interview APIs"]
  node_socket_gateway["WebSocket gateway<br/>[index.js]"]
  node_socket_auth["Socket authentication<br/>[middleware.js]"]
  node_socket_handler["Live interview handler<br/>[handler.js]"]
  node_browser["Interview client<br/>[interview.js]"]
end

subgraph group_services["Domain services"]
  node_user_service["User service<br/>[userServices.js]"]
  node_resume_service["Resume ingestion<br/>[resumeService.js]"]
  node_interview_service["Session &amp; scorecards"]
  node_redis_service["Active-session cache<br/>[redisService.js]"]
  node_cleanup["Session cleanup<br/>[sessionCleanup.js]"]
end

subgraph group_data["Persistence &amp; state"]
  node_user_model[("User records<br/>[user.js]")]
  node_resume_model[("Resume records<br/>[resume.js]")]
  node_interview_model[("Interview records<br/>[interview.js]")]
end

subgraph group_integrations["External integrations"]
  node_cashfree["Cashfree service<br/>[cashfreeService.js]"]
  node_aws["S3 file service<br/>[awsServices.js]"]
  node_gemini["Gemini AI service<br/>[geminiService.js]"]
  node_redis[("Redis")]
  node_brevo["Brevo email service<br/>[brevoService.js]"]
end

node_candidate(("Candidate"))

node_candidate -->|"uses"| node_app
node_app -->|"mounts"| node_user_routes
node_app -->|"mounts"| node_payment_routes
node_app -->|"mounts"| node_interview_routes
node_user_routes -->|"dispatches"| node_user_controller
node_user_routes -->|"protects"| node_auth
node_user_controller -->|"calls"| node_user_service
node_user_controller -->|"sends reset email"| node_brevo
node_user_service -->|"reads and writes"| node_user_model
node_auth -->|"loads user"| node_user_model
node_payment_routes -->|"dispatches"| node_payment_controller
node_payment_routes -->|"protects"| node_auth
node_payment_controller -->|"creates and checks orders"| node_cashfree
node_payment_controller -->|"updates order"| node_user_service
node_interview_routes -->|"dispatches"| node_interview_controller
node_interview_routes -->|"protects"| node_auth
node_interview_controller -->|"checks and saves resume"| node_resume_service
node_interview_controller -->|"requests upload URL"| node_aws
node_interview_controller -->|"queries and finalizes"| node_interview_service
node_interview_controller -->|"checks active session"| node_redis_service
node_resume_service -->|"downloads resume"| node_aws
node_resume_service -->|"parses resume"| node_gemini
node_resume_service -->|"reads and updates"| node_resume_model
node_socket_gateway -->|"authenticates"| node_socket_auth
node_socket_gateway -->|"dispatches"| node_socket_handler
node_socket_auth -->|"loads user"| node_user_model
node_socket_auth -->|"checks session"| node_interview_model
node_socket_auth -->|"checks session state"| node_redis_service
node_browser -.->|"opens live interview"| node_socket_gateway
node_socket_handler -->|"loads resume context"| node_resume_service
node_socket_handler -->|"manages session"| node_interview_service
node_socket_handler -->|"streams interview"| node_gemini
node_socket_handler -->|"tracks active session"| node_redis_service
node_interview_service -->|"stores transcript and scores"| node_interview_model
node_interview_service -->|"sets and clears session key"| node_redis_service
node_interview_service -->|"generates scorecard"| node_gemini
node_redis_service -->|"reads and writes keys"| node_redis
node_cleanup -->|"cleans stale sessions"| node_interview_service

click node_app "https://github.com/zendacross97/ai-interview-coach/blob/main/app.js"
click node_user_routes "https://github.com/zendacross97/ai-interview-coach/blob/main/routes/userRoutes.js"
click node_user_controller "https://github.com/zendacross97/ai-interview-coach/blob/main/controllers/userController.js"
click node_auth "https://github.com/zendacross97/ai-interview-coach/blob/main/middlewares/auth.js"
click node_user_service "https://github.com/zendacross97/ai-interview-coach/blob/main/services/userServices.js"
click node_user_model "https://github.com/zendacross97/ai-interview-coach/blob/main/model/user.js"
click node_payment_routes "https://github.com/zendacross97/ai-interview-coach/blob/main/routes/paymentRoute.js"
click node_payment_controller "https://github.com/zendacross97/ai-interview-coach/blob/main/controllers/paymentController.js"
click node_cashfree "https://github.com/zendacross97/ai-interview-coach/blob/main/services/cashfreeService.js"
click node_interview_routes "https://github.com/zendacross97/ai-interview-coach/blob/main/routes/interviewRoute.js"
click node_interview_controller "https://github.com/zendacross97/ai-interview-coach/blob/main/controllers/interviewController.js"
click node_resume_service "https://github.com/zendacross97/ai-interview-coach/blob/main/services/resumeService.js"
click node_resume_model "https://github.com/zendacross97/ai-interview-coach/blob/main/model/resume.js"
click node_aws "https://github.com/zendacross97/ai-interview-coach/blob/main/services/awsServices.js"
click node_gemini "https://github.com/zendacross97/ai-interview-coach/blob/main/services/geminiService.js"
click node_socket_gateway "https://github.com/zendacross97/ai-interview-coach/blob/main/ws/index.js"
click node_socket_auth "https://github.com/zendacross97/ai-interview-coach/blob/main/ws/middleware.js"
click node_socket_handler "https://github.com/zendacross97/ai-interview-coach/blob/main/ws/handler.js"
click node_interview_service "https://github.com/zendacross97/ai-interview-coach/blob/main/services/interviewService.js"
click node_interview_model "https://github.com/zendacross97/ai-interview-coach/blob/main/model/interview.js"
click node_redis_service "https://github.com/zendacross97/ai-interview-coach/blob/main/services/redisService.js"
click node_brevo "https://github.com/zendacross97/ai-interview-coach/blob/main/services/brevoService.js"
click node_cleanup "https://github.com/zendacross97/ai-interview-coach/blob/main/cron/sessionCleanup.js"
click node_browser "https://github.com/zendacross97/ai-interview-coach/blob/main/public/js/interview.js"

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_app,node_user_routes,node_user_controller,node_auth,node_payment_routes,node_payment_controller toneBlue
class node_interview_routes,node_interview_controller,node_socket_gateway,node_socket_auth,node_socket_handler,node_browser toneAmber
class node_user_service,node_resume_service,node_interview_service,node_redis_service,node_cleanup toneMint
class node_user_model,node_resume_model,node_interview_model toneRose
class node_cashfree,node_aws,node_gemini,node_redis,node_brevo,node_candidate toneIndigo
```

## Components

### Accounts & access

- [HTTP server](https://github.com/zendacross97/ai-interview-coach/blob/main/app.js): `app.js`
- [Account routes](https://github.com/zendacross97/ai-interview-coach/blob/main/routes/userRoutes.js): `routes/userRoutes.js`
- [Account workflows](https://github.com/zendacross97/ai-interview-coach/blob/main/controllers/userController.js): `controllers/userController.js`
- [JWT authentication](https://github.com/zendacross97/ai-interview-coach/blob/main/middlewares/auth.js): `middlewares/auth.js`
- [Payment routes](https://github.com/zendacross97/ai-interview-coach/blob/main/routes/paymentRoute.js): `routes/paymentRoute.js`
- [Payment workflow](https://github.com/zendacross97/ai-interview-coach/blob/main/controllers/paymentController.js): `controllers/paymentController.js`

### Interview experience

- [Interview routes](https://github.com/zendacross97/ai-interview-coach/blob/main/routes/interviewRoute.js): `routes/interviewRoute.js`
- [Interview APIs](https://github.com/zendacross97/ai-interview-coach/blob/main/controllers/interviewController.js): `controllers/interviewController.js`
- [WebSocket gateway](https://github.com/zendacross97/ai-interview-coach/blob/main/ws/index.js): `ws/index.js`
- [Socket authentication](https://github.com/zendacross97/ai-interview-coach/blob/main/ws/middleware.js): `ws/middleware.js`
- [Live interview handler](https://github.com/zendacross97/ai-interview-coach/blob/main/ws/handler.js): `ws/handler.js`
- [Interview client](https://github.com/zendacross97/ai-interview-coach/blob/main/public/js/interview.js): `public/js/interview.js`

### Domain services

- [User service](https://github.com/zendacross97/ai-interview-coach/blob/main/services/userServices.js): `services/userServices.js`
- [Resume ingestion](https://github.com/zendacross97/ai-interview-coach/blob/main/services/resumeService.js): `services/resumeService.js`
- [Session & scorecards](https://github.com/zendacross97/ai-interview-coach/blob/main/services/interviewService.js): `services/interviewService.js`
- [Active-session cache](https://github.com/zendacross97/ai-interview-coach/blob/main/services/redisService.js): `services/redisService.js`
- [Session cleanup](https://github.com/zendacross97/ai-interview-coach/blob/main/cron/sessionCleanup.js): `cron/sessionCleanup.js`

### Persistence & state

- [User records](https://github.com/zendacross97/ai-interview-coach/blob/main/model/user.js): `model/user.js`
- [Resume records](https://github.com/zendacross97/ai-interview-coach/blob/main/model/resume.js): `model/resume.js`
- [Interview records](https://github.com/zendacross97/ai-interview-coach/blob/main/model/interview.js): `model/interview.js`

### External integrations

- [Cashfree service](https://github.com/zendacross97/ai-interview-coach/blob/main/services/cashfreeService.js): `services/cashfreeService.js`
- [S3 file service](https://github.com/zendacross97/ai-interview-coach/blob/main/services/awsServices.js): `services/awsServices.js`
- [Gemini AI service](https://github.com/zendacross97/ai-interview-coach/blob/main/services/geminiService.js): `services/geminiService.js`
- **Redis**
- [Brevo email service](https://github.com/zendacross97/ai-interview-coach/blob/main/services/brevoService.js): `services/brevoService.js`

### Other components

- **Candidate**

## Connections

- Candidate → HTTP server: uses (evidence: `README.md`)
- HTTP server → Account routes: mounts (evidence: `app.js`)
- HTTP server → Payment routes: mounts (evidence: `app.js`)
- HTTP server → Interview routes: mounts (evidence: `app.js`)
- Account routes → Account workflows: dispatches (evidence: `routes/userRoutes.js`)
- Account routes → JWT authentication: protects (evidence: `routes/userRoutes.js`)
- Account workflows → User service: calls (evidence: `controllers/userController.js`)
- Account workflows → Brevo email service: sends reset email (evidence: `controllers/userController.js`)
- User service → User records: reads and writes (evidence: `services/userServices.js`)
- JWT authentication → User records: loads user (evidence: `middlewares/auth.js`)
- Payment routes → Payment workflow: dispatches (evidence: `routes/paymentRoute.js`)
- Payment routes → JWT authentication: protects (evidence: `routes/paymentRoute.js`)
- Payment workflow → Cashfree service: creates and checks orders (evidence: `controllers/paymentController.js`)
- Payment workflow → User service: updates order (evidence: `controllers/paymentController.js`)
- Interview routes → Interview APIs: dispatches (evidence: `routes/interviewRoute.js`)
- Interview routes → JWT authentication: protects (evidence: `routes/interviewRoute.js`)
- Interview APIs → Resume ingestion: checks and saves resume (evidence: `controllers/interviewController.js`)
- Interview APIs → S3 file service: requests upload URL (evidence: `controllers/interviewController.js`)
- Interview APIs → Session & scorecards: queries and finalizes (evidence: `controllers/interviewController.js`)
- Interview APIs → Active-session cache: checks active session (evidence: `controllers/interviewController.js`)
- Resume ingestion → S3 file service: downloads resume (evidence: `services/resumeService.js`)
- Resume ingestion → Gemini AI service: parses resume (evidence: `services/resumeService.js`)
- Resume ingestion → Resume records: reads and updates (evidence: `services/resumeService.js`)
- WebSocket gateway → Socket authentication: authenticates (evidence: `ws/index.js`)
- WebSocket gateway → Live interview handler: dispatches (evidence: `ws/index.js`)
- Socket authentication → User records: loads user (evidence: `ws/middleware.js`)
- Socket authentication → Interview records: checks session (evidence: `ws/middleware.js`)
- Socket authentication → Active-session cache: checks session state (evidence: `ws/middleware.js`)
- Interview client → WebSocket gateway: opens live interview
- Live interview handler → Resume ingestion: loads resume context (evidence: `ws/handler.js`)
- Live interview handler → Session & scorecards: manages session (evidence: `ws/handler.js`)
- Live interview handler → Gemini AI service: streams interview (evidence: `ws/handler.js`)
- Live interview handler → Active-session cache: tracks active session (evidence: `ws/handler.js`)
- Session & scorecards → Interview records: stores transcript and scores (evidence: `services/interviewService.js`)
- Session & scorecards → Active-session cache: sets and clears session key (evidence: `services/interviewService.js`)
- Session & scorecards → Gemini AI service: generates scorecard (evidence: `services/interviewService.js`)
- Active-session cache → Redis: reads and writes keys (evidence: `services/redisService.js`)
- Session cleanup → Session & scorecards: cleans stale sessions (evidence: `cron/sessionCleanup.js`)
