# subashs27/ai-interview-management-system architecture

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

- Interactive diagram: https://gitdiagram.com/subashs27/ai-interview-management-system
- Repository: https://github.com/subashs27/ai-interview-management-system

## Overview

This is a Streamlit AI interview system. Candidates submit a resume, receive a profile-informed interview, answer questions by voice, and see an evaluation and report. The main stages are resume parsing and analysis, knowledge lookup or generation, adaptive question selection, transcription and answer evaluation, follow-up/completion decisions, and report display. An admin page and SQLite-backed knowledge and interview records are additional capabilities. The README documents the end-to-end flow; some internal links rely on source-index references rather than complete excerpts.

Main entry points: [`pages/Candidate_v2.py`](https://github.com/subashs27/ai-interview-management-system/blob/main/pages/Candidate_v2.py) (Candidate interface), [`interview/interview_manager.py`](https://github.com/subashs27/ai-interview-management-system/blob/main/interview/interview_manager.py) (Interview lifecycle), [`generator.py`](https://github.com/subashs27/ai-interview-management-system/blob/main/generator.py) (Knowledge generation), [`evaluation/evaluation_engine.py`](https://github.com/subashs27/ai-interview-management-system/blob/main/evaluation/evaluation_engine.py) (Answer evaluation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_candidate["Candidate experience"]
  node_candidate_ui["Candidate interface<br/>[Candidate_v2.py]"]
end

subgraph group_preparation["Profile and knowledge"]
  node_resume_parser["Resume parser<br/>[resume_parser.py]"]
  node_resume_analyzer["Resume analyzer<br/>[resume_analyzer.py]"]
  node_knowledge_retriever["Knowledge retrieval"]
  node_knowledge_generator["Knowledge generation<br/>[generator.py]"]
  node_prompt["Generation prompts<br/>[prompt.py]"]
end

subgraph group_runtime["Interview runtime"]
  node_interview_manager["Interview lifecycle"]
  node_interview_engine["Question selection"]
  node_adaptive_engine["Adaptive decisions<br/>[adaptive_engine.py]"]
  node_interview_state["Interview state<br/>[interview_state.py]"]
  node_session["Session access<br/>[session.py]"]
  node_recorder["Voice recording<br/>[recorder.py]"]
  node_transcription["Speech transcription<br/>[speech_to_text.py]"]
  node_voice_analysis["Voice analysis<br/>[voice_analysis.py]"]
  node_evaluation["Answer evaluation"]
  node_evaluation_prompt["Evaluation prompt"]
  node_followup["Follow-up logic<br/>[followup_engine.py]"]
  node_report["Interview report"]
end

subgraph group_operations["Admin and persistence"]
  node_admin["Admin interface<br/>[admin.py]"]
  node_database[("SQLite records<br/>[database.py]")]
  node_schema["Database schema<br/>[schema.py]"]
end

node_candidate(("Candidate"))
node_gemini{{"Gemini API"}}

node_candidate -->|"uses"| node_candidate_ui
node_candidate_ui -->|"uploads resume"| node_resume_parser
node_resume_parser -->|"provides text"| node_resume_analyzer
node_resume_analyzer -->|"analyzes with"| node_gemini
node_candidate_ui -->|"retrieves knowledge"| node_knowledge_retriever
node_knowledge_retriever -->|"looks up topics"| node_database
node_admin -->|"generates topics"| node_knowledge_generator
node_knowledge_generator -->|"uses prompt"| node_prompt
node_knowledge_generator -->|"generates content"| node_gemini
node_knowledge_generator -->|"saves knowledge"| node_database
node_candidate_ui -->|"starts interview"| node_interview_manager
node_interview_manager -->|"gets state"| node_session
node_session -->|"provides state"| node_interview_state
node_interview_manager -->|"selects questions"| node_interview_engine
node_interview_manager -->|"chooses next step"| node_adaptive_engine
node_candidate_ui -->|"records answer"| node_recorder
node_candidate_ui -->|"transcribes audio"| node_transcription
node_transcription -->|"transcribes with"| node_gemini
node_candidate_ui -->|"analyzes voice"| node_voice_analysis
node_interview_manager -->|"evaluates answers"| node_evaluation
node_evaluation -->|"uses prompt"| node_evaluation_prompt
node_evaluation -->|"evaluates with"| node_gemini
node_interview_manager -.->|"handles follow-ups"| node_followup
node_interview_manager -->|"builds report"| node_report
node_candidate_ui -->|"displays report"| node_report
node_admin -.->|"reads records"| node_database
node_candidate_ui -->|"creates tables"| node_schema

click node_candidate_ui "https://github.com/subashs27/ai-interview-management-system/blob/main/pages/Candidate_v2.py"
click node_resume_parser "https://github.com/subashs27/ai-interview-management-system/blob/main/resume/resume_parser.py"
click node_resume_analyzer "https://github.com/subashs27/ai-interview-management-system/blob/main/resume/resume_analyzer.py"
click node_knowledge_retriever "https://github.com/subashs27/ai-interview-management-system/blob/main/knowledge/knowledge_retriever.py"
click node_knowledge_generator "https://github.com/subashs27/ai-interview-management-system/blob/main/generator.py"
click node_prompt "https://github.com/subashs27/ai-interview-management-system/blob/main/prompt.py"
click node_interview_manager "https://github.com/subashs27/ai-interview-management-system/blob/main/interview/interview_manager.py"
click node_interview_engine "https://github.com/subashs27/ai-interview-management-system/blob/main/interview/interview_engine.py"
click node_adaptive_engine "https://github.com/subashs27/ai-interview-management-system/blob/main/interview/adaptive_engine.py"
click node_interview_state "https://github.com/subashs27/ai-interview-management-system/blob/main/interview/interview_state.py"
click node_session "https://github.com/subashs27/ai-interview-management-system/blob/main/interview/session.py"
click node_recorder "https://github.com/subashs27/ai-interview-management-system/blob/main/voice/recorder.py"
click node_transcription "https://github.com/subashs27/ai-interview-management-system/blob/main/voice/speech_to_text.py"
click node_voice_analysis "https://github.com/subashs27/ai-interview-management-system/blob/main/voice/voice_analysis.py"
click node_evaluation "https://github.com/subashs27/ai-interview-management-system/blob/main/evaluation/evaluation_engine.py"
click node_evaluation_prompt "https://github.com/subashs27/ai-interview-management-system/blob/main/evaluation/evaluation_prompt.py"
click node_followup "https://github.com/subashs27/ai-interview-management-system/blob/main/interview/followup_engine.py"
click node_report "https://github.com/subashs27/ai-interview-management-system/blob/main/interview/interview_manager.py"
click node_admin "https://github.com/subashs27/ai-interview-management-system/blob/main/pages/admin.py"
click node_database "https://github.com/subashs27/ai-interview-management-system/blob/main/database/database.py"
click node_schema "https://github.com/subashs27/ai-interview-management-system/blob/main/database/schema.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_candidate_ui toneBlue
class node_resume_parser,node_resume_analyzer,node_knowledge_retriever,node_knowledge_generator,node_prompt toneAmber
class node_interview_manager,node_interview_engine,node_adaptive_engine,node_interview_state,node_session,node_recorder,node_transcription,node_voice_analysis,node_evaluation,node_evaluation_prompt,node_followup,node_report,node_gemini toneMint
class node_admin,node_database,node_schema toneRose
class node_candidate toneIndigo
```

## Components

### Candidate experience

- [Candidate interface](https://github.com/subashs27/ai-interview-management-system/blob/main/pages/Candidate_v2.py): `pages/Candidate_v2.py`

### Profile and knowledge

- [Resume parser](https://github.com/subashs27/ai-interview-management-system/blob/main/resume/resume_parser.py): `resume/resume_parser.py`
- [Resume analyzer](https://github.com/subashs27/ai-interview-management-system/blob/main/resume/resume_analyzer.py): `resume/resume_analyzer.py`
- [Knowledge retrieval](https://github.com/subashs27/ai-interview-management-system/blob/main/knowledge/knowledge_retriever.py): `knowledge/knowledge_retriever.py`
- [Knowledge generation](https://github.com/subashs27/ai-interview-management-system/blob/main/generator.py): `generator.py`
- [Generation prompts](https://github.com/subashs27/ai-interview-management-system/blob/main/prompt.py): `prompt.py`

### Interview runtime

- [Interview lifecycle](https://github.com/subashs27/ai-interview-management-system/blob/main/interview/interview_manager.py): `interview/interview_manager.py`
- [Question selection](https://github.com/subashs27/ai-interview-management-system/blob/main/interview/interview_engine.py): `interview/interview_engine.py`
- [Adaptive decisions](https://github.com/subashs27/ai-interview-management-system/blob/main/interview/adaptive_engine.py): `interview/adaptive_engine.py`
- [Interview state](https://github.com/subashs27/ai-interview-management-system/blob/main/interview/interview_state.py): `interview/interview_state.py`
- [Session access](https://github.com/subashs27/ai-interview-management-system/blob/main/interview/session.py): `interview/session.py`
- [Voice recording](https://github.com/subashs27/ai-interview-management-system/blob/main/voice/recorder.py): `voice/recorder.py`
- [Speech transcription](https://github.com/subashs27/ai-interview-management-system/blob/main/voice/speech_to_text.py): `voice/speech_to_text.py`
- [Voice analysis](https://github.com/subashs27/ai-interview-management-system/blob/main/voice/voice_analysis.py): `voice/voice_analysis.py`
- [Answer evaluation](https://github.com/subashs27/ai-interview-management-system/blob/main/evaluation/evaluation_engine.py): `evaluation/evaluation_engine.py`
- [Evaluation prompt](https://github.com/subashs27/ai-interview-management-system/blob/main/evaluation/evaluation_prompt.py): `evaluation/evaluation_prompt.py`
- [Follow-up logic](https://github.com/subashs27/ai-interview-management-system/blob/main/interview/followup_engine.py): `interview/followup_engine.py`
- [Interview report](https://github.com/subashs27/ai-interview-management-system/blob/main/interview/interview_manager.py): `interview/interview_manager.py`

### Admin and persistence

- [Admin interface](https://github.com/subashs27/ai-interview-management-system/blob/main/pages/admin.py): `pages/admin.py`
- [SQLite records](https://github.com/subashs27/ai-interview-management-system/blob/main/database/database.py): `database/database.py`
- [Database schema](https://github.com/subashs27/ai-interview-management-system/blob/main/database/schema.py): `database/schema.py`

### Other components

- **Candidate**
- **Gemini API**

## Connections

- Candidate → Candidate interface: uses (evidence: `README.md`)
- Candidate interface → Resume parser: uploads resume (evidence: `README.md`)
- Resume parser → Resume analyzer: provides text (evidence: `README.md`)
- Resume analyzer → Gemini API: analyzes with (evidence: `resume/resume_analyzer.py`)
- Candidate interface → Knowledge retrieval: retrieves knowledge (evidence: `pages/Candidate_v2.py`)
- Knowledge retrieval → SQLite records: looks up topics (evidence: `knowledge/knowledge_retriever.py`)
- Admin interface → Knowledge generation: generates topics (evidence: `pages/admin.py`)
- Knowledge generation → Generation prompts: uses prompt (evidence: `generator.py`)
- Knowledge generation → Gemini API: generates content (evidence: `generator.py`)
- Knowledge generation → SQLite records: saves knowledge (evidence: `generator.py`)
- Candidate interface → Interview lifecycle: starts interview (evidence: `pages/Candidate_v2.py`)
- Interview lifecycle → Session access: gets state (evidence: `interview/interview_manager.py`)
- Session access → Interview state: provides state (evidence: `interview/session.py`)
- Interview lifecycle → Question selection: selects questions (evidence: `interview/interview_manager.py`)
- Interview lifecycle → Adaptive decisions: chooses next step (evidence: `interview/interview_manager.py`)
- Candidate interface → Voice recording: records answer (evidence: `pages/Candidate_v2.py`)
- Candidate interface → Speech transcription: transcribes audio (evidence: `pages/Candidate_v2.py`)
- Speech transcription → Gemini API: transcribes with (evidence: `voice/speech_to_text.py`)
- Candidate interface → Voice analysis: analyzes voice (evidence: `pages/Candidate_v2.py`)
- Interview lifecycle → Answer evaluation: evaluates answers (evidence: `interview/interview_manager.py`)
- Answer evaluation → Evaluation prompt: uses prompt (evidence: `evaluation/evaluation_engine.py`)
- Answer evaluation → Gemini API: evaluates with (evidence: `evaluation/evaluation_engine.py`)
- Interview lifecycle → Follow-up logic: handles follow-ups
- Interview lifecycle → Interview report: builds report (evidence: `interview/interview_manager.py`)
- Candidate interface → Interview report: displays report (evidence: `pages/Candidate_v2.py`)
- Admin interface → SQLite records: reads records
- Candidate interface → Database schema: creates tables (evidence: `pages/Candidate_v2.py`)
