# elangkumaran2004/ai-mock-interviewer architecture

> Architecture diagram of the GitHub repository elangkumaran2004/ai-mock-interviewer, 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/elangkumaran2004/ai-mock-interviewer
- Repository: https://github.com/elangkumaran2004/ai-mock-interviewer

## Overview

AI Mock Interviewer is a local Streamlit app for timed technical or HR interview practice. Candidates choose topics, level, and duration, then answer each generated question by typing or speaking; answers are scored and the completed session produces a coaching report and Markdown download. The graph follows the documented workflow and sampled modules. Some UI calls are in omitted app.py excerpts, so those relationships are grounded in the README rather than presented as inspected source details.

Main entry points: [`app.py`](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/app.py) (Streamlit screens), [`interviewer/questions.py`](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/questions.py) (Question writer), [`interviewer/judge.py`](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/judge.py) (Answer judge), [`interviewer/llm.py`](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/llm.py) (Structured LLM client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Interview experience"]
  node_ui["Streamlit screens<br/>[app.py]"]
  node_session["Interview session<br/>[session.py]"]
  node_voice["Voice transcription<br/>[speech.py]"]
end

subgraph group_questioning["Question generation"]
  node_question_writer["Question writer<br/>[questions.py]"]
  node_topic_config["Topics and levels<br/>[config.py]"]
end

subgraph group_evaluation["Answer evaluation"]
  node_answer_judge["Answer judge<br/>[judge.py]"]
  node_report_builder["Report builder<br/>[report.py]"]
end

subgraph group_support["Shared services"]
  node_schemas["Validated data models<br/>[schemas.py]"]
  node_llm_client["Structured LLM client<br/>[llm.py]"]
end

node_candidate(("Candidate"))
node_ollama{{"Ollama model"}}
node_whisper{{"faster-whisper"}}

node_candidate -->|"sets up and answers"| node_ui
node_ui -->|"requests first question"| node_question_writer
node_ui -->|"starts and advances"| node_session
node_ui -->|"submits recording"| node_voice
node_voice -->|"transcribes audio"| node_whisper
node_ui -->|"submits answer"| node_answer_judge
node_session -->|"writes next question"| node_question_writer
node_question_writer -->|"uses topics and levels"| node_topic_config
node_question_writer -->|"generates questions"| node_llm_client
node_answer_judge -->|"uses level rubric"| node_topic_config
node_answer_judge -->|"scores answer"| node_llm_client
node_report_builder -->|"writes coaching summary"| node_llm_client
node_report_builder -->|"provides report and download"| node_ui
node_llm_client -->|"requests structured output"| node_ollama
node_question_writer -->|"validates generated data"| node_schemas
node_answer_judge -->|"returns score model"| node_schemas
node_report_builder -->|"returns summary model"| node_schemas

click node_ui "https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/app.py"
click node_session "https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/session.py"
click node_voice "https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/speech.py"
click node_question_writer "https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/questions.py"
click node_topic_config "https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/config.py"
click node_answer_judge "https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/judge.py"
click node_report_builder "https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/report.py"
click node_schemas "https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/schemas.py"
click node_llm_client "https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/llm.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_ui,node_session,node_voice toneBlue
class node_question_writer,node_topic_config toneAmber
class node_answer_judge,node_report_builder toneMint
class node_schemas,node_llm_client toneRose
class node_candidate,node_ollama,node_whisper toneIndigo
```

## Components

### Interview experience

- [Streamlit screens](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/app.py): `app.py`
- [Interview session](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/session.py): `interviewer/session.py`
- [Voice transcription](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/speech.py): `interviewer/speech.py`

### Question generation

- [Question writer](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/questions.py): `interviewer/questions.py`
- [Topics and levels](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/config.py): `interviewer/config.py`

### Answer evaluation

- [Answer judge](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/judge.py): `interviewer/judge.py`
- [Report builder](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/report.py): `interviewer/report.py`

### Shared services

- [Validated data models](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/schemas.py): `interviewer/schemas.py`
- [Structured LLM client](https://github.com/elangkumaran2004/ai-mock-interviewer/blob/main/interviewer/llm.py): `interviewer/llm.py`

### Other components

- **Candidate**
- **Ollama model**
- **faster-whisper**

## Connections

- Candidate → Streamlit screens: sets up and answers (evidence: `README.md`)
- Streamlit screens → Question writer: requests first question (evidence: `README.md`)
- Streamlit screens → Interview session: starts and advances (evidence: `README.md`)
- Streamlit screens → Voice transcription: submits recording (evidence: `README.md`)
- Voice transcription → faster-whisper: transcribes audio (evidence: `README.md`)
- Streamlit screens → Answer judge: submits answer (evidence: `README.md`)
- Interview session → Question writer: writes next question (evidence: `README.md`)
- Question writer → Topics and levels: uses topics and levels (evidence: `interviewer/questions.py`)
- Question writer → Structured LLM client: generates questions (evidence: `interviewer/questions.py`)
- Answer judge → Topics and levels: uses level rubric (evidence: `interviewer/judge.py`)
- Answer judge → Structured LLM client: scores answer (evidence: `interviewer/judge.py`)
- Report builder → Structured LLM client: writes coaching summary (evidence: `interviewer/report.py`)
- Report builder → Streamlit screens: provides report and download (evidence: `README.md`)
- Structured LLM client → Ollama model: requests structured output (evidence: `interviewer/llm.py`)
- Question writer → Validated data models: validates generated data (evidence: `interviewer/questions.py`)
- Answer judge → Validated data models: returns score model (evidence: `interviewer/judge.py`)
- Report builder → Validated data models: returns summary model (evidence: `interviewer/report.py`)
