# akshay001-a/ai-hr-interview-system architecture

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

- Interactive diagram: https://gitdiagram.com/akshay001-a/ai-hr-interview-system
- Repository: https://github.com/akshay001-a/ai-hr-interview-system

## Overview

Interview Studio guides a student from resume and job-description review through personalized HR practice, answer capture, feedback, and saved reports. The README documents the shared dashboard/backend and the interview-to-feedback handoff; sampled routes and services establish key backend calls. Some frontend-to-backend links and unsampled subsystems are documented but not directly shown in source excerpts.

Main entry points: [`modules/interview_engine/backend/routes.py`](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/routes.py) (Interview endpoints), [`frontend/src/App.jsx`](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/frontend/src/App.jsx) (Dashboard), [`modules/interview_engine/frontend/InterviewApp.jsx`](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/InterviewApp.jsx) (Interview experience), [`modules/interview_engine/frontend/src/InterviewRoom.jsx`](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/InterviewRoom.jsx) (Interview room)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workspace["Shared workspace"]
  node_dashboard["Dashboard<br/>[App.jsx]"]
  node_workspace_ui["Workspace navigation<br/>[Workspace.jsx]"]
  node_feedback_validation["Report validation<br/>[feedback.js]"]
end

subgraph group_interview["Interview preparation"]
  node_interview_ui["Interview experience<br/>[InterviewApp.jsx]"]
  node_document_ui["Document review"]
  node_question_ui["Question studio<br/>[QuestionStudio.jsx]"]
  node_room_ui["Interview room<br/>[InterviewRoom.jsx]"]
  node_session_state["Session and drafts"]
  node_voice["Voice input<br/>[voiceInput.js]"]
  node_interview_api["Interview API client<br/>[api.js]"]
  node_interview_routes["Interview endpoints<br/>[routes.py]"]
  node_pdf["PDF extraction<br/>[pdf_service.py]"]
  node_profile["Profile extraction and comparison<br/>[profile_service.py]"]
  node_question_service["Question planning"]
  node_generation["Model generation runtime"]
  node_followup["Adaptive follow-ups"]
  node_session_service["Session completion<br/>[session_service.py]"]
end

subgraph group_feedback["Feedback and reports"]
  node_feedback_ui["Feedback and report views<br/>[FeedbackApp.jsx]"]
  node_feedback_routes["Feedback endpoints<br/>[routes.py]"]
  node_feedback_service["Report generation"]
  node_evaluation["Answer evaluation"]
  node_communication["Communication analysis"]
  node_database[("Report storage<br/>[database.py]")]
end

subgraph group_foundation["Shared backend"]
  node_api["Shared API<br/>[api.js]"]
  node_api_server["API application<br/>[main.py]"]
  node_settings["Application settings<br/>[config.py]"]
  node_contracts["Completed interview contract<br/>[contracts.py]"]
end

node_student(("Student"))
node_gemini{{"Gemini"}}

node_student -->|"uses"| node_dashboard
node_dashboard -->|"renders"| node_workspace_ui
node_dashboard -->|"embeds"| node_interview_ui
node_dashboard -->|"embeds"| node_feedback_ui
node_interview_ui -->|"renders"| node_document_ui
node_interview_ui -->|"renders"| node_question_ui
node_interview_ui -->|"renders"| node_room_ui
node_document_ui -->|"requests"| node_interview_api
node_room_ui -->|"requests"| node_interview_api
node_room_ui -->|"uses"| node_session_state
node_room_ui -->|"uses"| node_voice
node_interview_api -.->|"calls"| node_interview_routes
node_dashboard -->|"requests"| node_api
node_api -.->|"calls"| node_feedback_routes
node_api_server -->|"registers"| node_interview_routes
node_api_server -->|"registers"| node_feedback_routes
node_interview_routes -->|"extracts PDFs"| node_pdf
node_interview_routes -->|"extracts profiles"| node_profile
node_interview_routes -->|"generates plans"| node_question_service
node_interview_routes -->|"generates follow-ups"| node_followup
node_interview_routes -->|"completes sessions"| node_session_service
node_question_service -->|"uses reviewed profile"| node_profile
node_question_service -->|"requests generation"| node_generation
node_generation -->|"generates content"| node_gemini
node_followup -->|"reuses generation"| node_question_service
node_session_service -->|"hands off session"| node_contracts
node_feedback_routes -->|"evaluates interview"| node_feedback_service
node_feedback_service -->|"evaluates answers"| node_evaluation
node_feedback_service -->|"analyzes answers"| node_communication
node_feedback_service -->|"saves report"| node_database
node_feedback_routes -->|"reads history"| node_database
node_feedback_ui -->|"validates report"| node_feedback_validation
node_feedback_ui -->|"requests reports"| node_api
node_settings -->|"configures storage"| node_database

click node_dashboard "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/frontend/src/App.jsx"
click node_workspace_ui "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/frontend/src/Workspace.jsx"
click node_interview_ui "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/InterviewApp.jsx"
click node_document_ui "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/DocumentPreparation.jsx"
click node_question_ui "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/QuestionStudio.jsx"
click node_room_ui "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/InterviewRoom.jsx"
click node_session_state "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/interviewSession.js"
click node_voice "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/voiceInput.js"
click node_interview_api "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/api.js"
click node_api "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/frontend/src/api.js"
click node_api_server "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/backend/main.py"
click node_settings "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/backend/config.py"
click node_contracts "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/backend/contracts.py"
click node_interview_routes "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/routes.py"
click node_pdf "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/pdf_service.py"
click node_profile "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/profile_service.py"
click node_question_service "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/question_service.py"
click node_generation "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/generation_runtime.py"
click node_followup "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/followup_service.py"
click node_session_service "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/session_service.py"
click node_feedback_ui "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/frontend/FeedbackApp.jsx"
click node_feedback_validation "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/frontend/src/feedback.js"
click node_feedback_routes "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/routes.py"
click node_feedback_service "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/feedback_service.py"
click node_evaluation "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/evaluation_service.py"
click node_communication "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/communication_service.py"
click node_database "https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/database.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_dashboard,node_workspace_ui,node_feedback_validation toneBlue
class node_interview_ui,node_document_ui,node_question_ui,node_room_ui,node_session_state,node_voice,node_interview_api,node_interview_routes,node_pdf,node_profile,node_question_service,node_generation,node_followup,node_session_service toneAmber
class node_feedback_ui,node_feedback_routes,node_feedback_service,node_evaluation,node_communication,node_database toneMint
class node_api,node_api_server,node_settings,node_contracts toneRose
class node_student,node_gemini toneIndigo
```

## Components

### Shared workspace

- [Dashboard](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Workspace navigation](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/frontend/src/Workspace.jsx): `frontend/src/Workspace.jsx`
- [Report validation](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/frontend/src/feedback.js): `frontend/src/feedback.js`

### Interview preparation

- [Interview experience](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/InterviewApp.jsx): `modules/interview_engine/frontend/InterviewApp.jsx`
- [Document review](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/DocumentPreparation.jsx): `modules/interview_engine/frontend/src/DocumentPreparation.jsx`
- [Question studio](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/QuestionStudio.jsx): `modules/interview_engine/frontend/src/QuestionStudio.jsx`
- [Interview room](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/InterviewRoom.jsx): `modules/interview_engine/frontend/src/InterviewRoom.jsx`
- [Session and drafts](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/interviewSession.js): `modules/interview_engine/frontend/src/interviewSession.js`
- [Voice input](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/voiceInput.js): `modules/interview_engine/frontend/src/voiceInput.js`
- [Interview API client](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/frontend/src/api.js): `modules/interview_engine/frontend/src/api.js`
- [Interview endpoints](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/routes.py): `modules/interview_engine/backend/routes.py`
- [PDF extraction](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/pdf_service.py): `modules/interview_engine/backend/pdf_service.py`
- [Profile extraction and comparison](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/profile_service.py): `modules/interview_engine/backend/profile_service.py`
- [Question planning](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/question_service.py): `modules/interview_engine/backend/question_service.py`
- [Model generation runtime](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/generation_runtime.py): `modules/interview_engine/backend/generation_runtime.py`
- [Adaptive follow-ups](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/followup_service.py): `modules/interview_engine/backend/followup_service.py`
- [Session completion](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/interview_engine/backend/session_service.py): `modules/interview_engine/backend/session_service.py`

### Feedback and reports

- [Feedback and report views](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/frontend/FeedbackApp.jsx): `modules/feedback_engine/frontend/FeedbackApp.jsx`
- [Feedback endpoints](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/routes.py): `modules/feedback_engine/backend/routes.py`
- [Report generation](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/feedback_service.py): `modules/feedback_engine/backend/feedback_service.py`
- [Answer evaluation](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/evaluation_service.py): `modules/feedback_engine/backend/evaluation_service.py`
- [Communication analysis](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/communication_service.py): `modules/feedback_engine/backend/communication_service.py`
- [Report storage](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/modules/feedback_engine/backend/database.py): `modules/feedback_engine/backend/database.py`

### Shared backend

- [Shared API](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [API application](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/backend/main.py): `backend/main.py`
- [Application settings](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/backend/config.py): `backend/config.py`
- [Completed interview contract](https://github.com/akshay001-a/ai-hr-interview-system/blob/main/backend/contracts.py): `backend/contracts.py`

### Other components

- **Student**
- **Gemini**

## Connections

- Student → Dashboard: uses (evidence: `README.md`)
- Dashboard → Workspace navigation: renders (evidence: `frontend/src/App.jsx`)
- Dashboard → Interview experience: embeds (evidence: `frontend/src/App.jsx`)
- Dashboard → Feedback and report views: embeds (evidence: `frontend/src/App.jsx`)
- Interview experience → Document review: renders (evidence: `modules/interview_engine/frontend/InterviewApp.jsx`)
- Interview experience → Question studio: renders (evidence: `modules/interview_engine/frontend/InterviewApp.jsx`)
- Interview experience → Interview room: renders (evidence: `modules/interview_engine/frontend/InterviewApp.jsx`)
- Document review → Interview API client: requests (evidence: `modules/interview_engine/frontend/src/DocumentPreparation.jsx`)
- Interview room → Interview API client: requests (evidence: `modules/interview_engine/frontend/src/InterviewRoom.jsx`)
- Interview room → Session and drafts: uses (evidence: `modules/interview_engine/frontend/src/InterviewRoom.jsx`)
- Interview room → Voice input: uses (evidence: `modules/interview_engine/frontend/src/InterviewRoom.jsx`)
- Interview API client → Interview endpoints: calls
- Dashboard → Shared API: requests (evidence: `frontend/src/App.jsx`)
- Shared API → Feedback endpoints: calls
- API application → Interview endpoints: registers (evidence: `backend/main.py`)
- API application → Feedback endpoints: registers (evidence: `backend/main.py`)
- Interview endpoints → PDF extraction: extracts PDFs (evidence: `modules/interview_engine/backend/routes.py`)
- Interview endpoints → Profile extraction and comparison: extracts profiles (evidence: `modules/interview_engine/backend/routes.py`)
- Interview endpoints → Question planning: generates plans (evidence: `modules/interview_engine/backend/routes.py`)
- Interview endpoints → Adaptive follow-ups: generates follow-ups (evidence: `modules/interview_engine/backend/routes.py`)
- Interview endpoints → Session completion: completes sessions (evidence: `modules/interview_engine/backend/routes.py`)
- Question planning → Profile extraction and comparison: uses reviewed profile (evidence: `modules/interview_engine/backend/question_service.py`)
- Question planning → Model generation runtime: requests generation (evidence: `modules/interview_engine/backend/question_service.py`)
- Model generation runtime → Gemini: generates content (evidence: `modules/interview_engine/backend/generation_runtime.py`)
- Adaptive follow-ups → Question planning: reuses generation (evidence: `modules/interview_engine/backend/followup_service.py`)
- Session completion → Completed interview contract: hands off session (evidence: `README.md`)
- Feedback endpoints → Report generation: evaluates interview (evidence: `modules/feedback_engine/backend/routes.py`)
- Report generation → Answer evaluation: evaluates answers (evidence: `modules/feedback_engine/backend/feedback_service.py`)
- Report generation → Communication analysis: analyzes answers (evidence: `modules/feedback_engine/backend/feedback_service.py`)
- Report generation → Report storage: saves report (evidence: `modules/feedback_engine/backend/feedback_service.py`)
- Feedback endpoints → Report storage: reads history (evidence: `modules/feedback_engine/backend/routes.py`)
- Feedback and report views → Report validation: validates report (evidence: `modules/feedback_engine/frontend/FeedbackApp.jsx`)
- Feedback and report views → Shared API: requests reports (evidence: `modules/feedback_engine/frontend/FeedbackApp.jsx`)
- Application settings → Report storage: configures storage (evidence: `modules/feedback_engine/backend/database.py`)
