# mukesh631102/ai-interviewer architecture

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

- Interactive diagram: https://gitdiagram.com/mukesh631102/ai-interviewer
- Repository: https://github.com/mukesh631102/ai-interviewer

## Overview

Open Source AI Interviewer is a Flask/Socket.IO app for role-specific mock interviews. The workflow runs from browser role selection, through speech capture and a live AI question/answer exchange, to an evaluation report. The README also documents webcam preview and browser speech synthesis; those client capabilities are represented, though their templates were not sampled. The graph follows shown route and event handlers; no persistent store is present, and chat history is held in app memory.

Main entry points: [`app.py`](https://github.com/mukesh631102/ai-interviewer/blob/main/app.py) (Socket Events), [`static/js/interview.js`](https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/interview.js) (Live Interview), [`templates/index.html`](https://github.com/mukesh631102/ai-interviewer/blob/main/templates/index.html) (Role Selection), [`static/js/main.js`](https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/main.js) (Start Session)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser Experience"]
  node_landing["Role Selection<br/>[index.html]"]
  node_landing_logic["Start Session<br/>[main.js]"]
  node_interview_room["Interview Room<br/>[interview.html]"]
  node_interview_ui["Live Interview<br/>[interview.js]"]
  node_camera_mic["Camera Preview<br/>[interview.js]"]
  node_speech_capture["Speech Capture<br/>[interview.js]"]
  node_speech_output["Voice Responses<br/>[interview.js]"]
  node_report_view["Report Page<br/>[report.html]"]
end

subgraph group_server["Interview Server"]
  node_flask_routes["Page Routes<br/>[app.py]"]
  node_socket_handlers["Socket Events<br/>[app.py]"]
  node_chat_history[("Session History<br/>[app.py]")]
end

subgraph group_intelligence["Interview Intelligence"]
  node_transcript_cleaner["Transcript Cleanup<br/>[audio_processor.py]"]
  node_interview_agent["Question Agent<br/>[ai_agent.py]"]
  node_evaluator["Report Evaluator<br/>[evaluator.py]"]
end

node_candidate(("Candidate"))
node_groq{{"Groq API"}}

node_candidate -->|"chooses role"| node_landing
node_landing -->|"starts session"| node_landing_logic
node_landing_logic -->|"navigates to"| node_flask_routes
node_candidate -->|"answers aloud"| node_interview_ui
node_interview_ui -->|"requests media"| node_camera_mic
node_interview_ui -->|"starts recognition"| node_speech_capture
node_speech_capture -->|"emits answer"| node_socket_handlers
node_socket_handlers -->|"cleans transcript"| node_transcript_cleaner
node_socket_handlers -->|"appends turns"| node_chat_history
node_socket_handlers -->|"requests response"| node_interview_agent
node_interview_agent -->|"requests completion"| node_groq
node_socket_handlers -->|"emits question"| node_interview_ui
node_interview_ui -->|"speaks response"| node_speech_output
node_candidate -->|"ends interview"| node_interview_ui
node_interview_ui -->|"requests report"| node_socket_handlers
node_socket_handlers -->|"reads transcript"| node_chat_history
node_socket_handlers -->|"generates report"| node_evaluator
node_evaluator -->|"requests evaluation"| node_groq
node_socket_handlers -->|"returns report"| node_interview_ui
node_interview_ui -->|"navigates to"| node_report_view
node_flask_routes -->|"renders page"| node_landing
node_flask_routes -->|"renders page"| node_interview_room
node_flask_routes -->|"renders page"| node_report_view

click node_landing "https://github.com/mukesh631102/ai-interviewer/blob/main/templates/index.html"
click node_landing_logic "https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/main.js"
click node_interview_room "https://github.com/mukesh631102/ai-interviewer/blob/main/templates/interview.html"
click node_interview_ui "https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/interview.js"
click node_camera_mic "https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/interview.js"
click node_speech_capture "https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/interview.js"
click node_speech_output "https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/interview.js"
click node_report_view "https://github.com/mukesh631102/ai-interviewer/blob/main/templates/report.html"
click node_flask_routes "https://github.com/mukesh631102/ai-interviewer/blob/main/app.py"
click node_socket_handlers "https://github.com/mukesh631102/ai-interviewer/blob/main/app.py"
click node_chat_history "https://github.com/mukesh631102/ai-interviewer/blob/main/app.py"
click node_transcript_cleaner "https://github.com/mukesh631102/ai-interviewer/blob/main/utils/audio_processor.py"
click node_interview_agent "https://github.com/mukesh631102/ai-interviewer/blob/main/utils/ai_agent.py"
click node_evaluator "https://github.com/mukesh631102/ai-interviewer/blob/main/utils/evaluator.py"

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_landing,node_landing_logic,node_interview_room,node_interview_ui,node_camera_mic,node_speech_capture,node_speech_output,node_report_view toneBlue
class node_flask_routes,node_socket_handlers,node_chat_history toneAmber
class node_transcript_cleaner,node_interview_agent,node_evaluator,node_groq toneMint
class node_candidate toneIndigo
```

## Components

### Browser Experience

- [Role Selection](https://github.com/mukesh631102/ai-interviewer/blob/main/templates/index.html): `templates/index.html`
- [Start Session](https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/main.js): `static/js/main.js`
- [Interview Room](https://github.com/mukesh631102/ai-interviewer/blob/main/templates/interview.html): `templates/interview.html`
- [Live Interview](https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/interview.js): `static/js/interview.js`
- [Camera Preview](https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/interview.js): `static/js/interview.js`
- [Speech Capture](https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/interview.js): `static/js/interview.js`
- [Voice Responses](https://github.com/mukesh631102/ai-interviewer/blob/main/static/js/interview.js): `static/js/interview.js`
- [Report Page](https://github.com/mukesh631102/ai-interviewer/blob/main/templates/report.html): `templates/report.html`

### Interview Server

- [Page Routes](https://github.com/mukesh631102/ai-interviewer/blob/main/app.py): `app.py`
- [Socket Events](https://github.com/mukesh631102/ai-interviewer/blob/main/app.py): `app.py`
- [Session History](https://github.com/mukesh631102/ai-interviewer/blob/main/app.py): `app.py`

### Interview Intelligence

- [Transcript Cleanup](https://github.com/mukesh631102/ai-interviewer/blob/main/utils/audio_processor.py): `utils/audio_processor.py`
- [Question Agent](https://github.com/mukesh631102/ai-interviewer/blob/main/utils/ai_agent.py): `utils/ai_agent.py`
- [Report Evaluator](https://github.com/mukesh631102/ai-interviewer/blob/main/utils/evaluator.py): `utils/evaluator.py`

### Other components

- **Candidate**
- **Groq API**

## Connections

- Candidate → Role Selection: chooses role (evidence: `README.md`)
- Role Selection → Start Session: starts session (evidence: `README.md`)
- Start Session → Page Routes: navigates to (evidence: `static/js/main.js`)
- Candidate → Live Interview: answers aloud (evidence: `README.md`)
- Live Interview → Camera Preview: requests media (evidence: `static/js/interview.js`)
- Live Interview → Speech Capture: starts recognition (evidence: `static/js/interview.js`)
- Speech Capture → Socket Events: emits answer (evidence: `static/js/interview.js`)
- Socket Events → Transcript Cleanup: cleans transcript (evidence: `app.py`)
- Socket Events → Session History: appends turns (evidence: `app.py`)
- Socket Events → Question Agent: requests response (evidence: `app.py`)
- Question Agent → Groq API: requests completion (evidence: `utils/ai_agent.py`)
- Socket Events → Live Interview: emits question (evidence: `app.py`)
- Live Interview → Voice Responses: speaks response (evidence: `static/js/interview.js`)
- Candidate → Live Interview: ends interview (evidence: `README.md`)
- Live Interview → Socket Events: requests report (evidence: `static/js/interview.js`)
- Socket Events → Session History: reads transcript (evidence: `app.py`)
- Socket Events → Report Evaluator: generates report (evidence: `app.py`)
- Report Evaluator → Groq API: requests evaluation (evidence: `utils/evaluator.py`)
- Socket Events → Live Interview: returns report (evidence: `app.py`)
- Live Interview → Report Page: navigates to (evidence: `static/js/interview.js`)
- Page Routes → Role Selection: renders page (evidence: `app.py`)
- Page Routes → Interview Room: renders page (evidence: `app.py`)
- Page Routes → Report Page: renders page (evidence: `app.py`)
