# hamza-24-ai/intraai architecture

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

- Interactive diagram: https://gitdiagram.com/hamza-24-ai/intraai
- Repository: https://github.com/hamza-24-ai/intraai

## Overview

IntraAI is a resume-personalized interview-practice product with two practice modes: a skill-based question bank and an adaptive spoken or typed live interview. The main workflow runs from resume upload and skill/role confirmation through question generation or live interview turns to a scored feedback report; signed-in users can also revisit history. The README documents the product stages, while excerpts show selected backend routing, session setup, adaptive logic, and persistence. Several frontend-to-API and unsampled agent relationships are therefore not asserted.

Main entry points: [`backened/app/routers/live_interview.py`](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/live_interview.py) (Live interview runtime), [`backened/app/routers/resumes.py`](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/resumes.py) (Resume handling), [`backened/app/routers/interview_sessions.py`](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/interview_sessions.py) (Interview setup), [`backened/app/cores/auth_dependancy.py`](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/cores/auth_dependancy.py) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_practice_setup["Practice setup"]
  node_resume_ui["Resume upload"]
  node_resume_api["Resume handling<br/>[resumes.py]"]
  node_resume_agent["Resume parser"]
  node_resume_context["Resume context<br/>[resume_context.py]"]
end

subgraph group_question_bank["Question bank"]
  node_question_ui["Question bank"]
  node_question_api["Question generation API<br/>[questions.py]"]
  node_question_agent["Question generator"]
end

subgraph group_live_interview["Live interview"]
  node_live_setup["Interview setup"]
  node_live_ui["Live interview screen<br/>[live-view.tsx]"]
  node_live_api["Live interview runtime<br/>[live_interview.py]"]
  node_live_graph["Interview agent graph<br/>[livegraph.py]"]
  node_stt["Speech recognition<br/>[stt.py]"]
  node_tts["Speech synthesis<br/>[tts.py]"]
  node_difficulty["Difficulty controller"]
  node_time_skip["Silence handler"]
end

subgraph group_reports_history["Reports and history"]
  node_feedback_agent["Feedback synthesis"]
  node_report_ui["Report view<br/>[report-view.tsx]"]
  node_history_ui["History view<br/>[history-view.tsx]"]
end

subgraph group_platform["Platform services"]
  node_auth["Authentication<br/>[auth_dependancy.py]"]
  node_db[("Relational database<br/>[database.py]")]
  node_models["Product records"]
  node_supabase["Supabase auth<br/>[supabase_client.py]"]
end

node_candidate(("Candidate"))

node_candidate -->|"uploads resume"| node_resume_ui
node_resume_ui -.->|"submits resume"| node_resume_api
node_resume_api -.->|"parses resume"| node_resume_agent
node_resume_api -.->|"resolves skills"| node_resume_context
node_candidate -->|"studies questions"| node_question_ui
node_question_api -.->|"generates questions"| node_question_agent
node_candidate -->|"starts interview"| node_live_setup
node_live_setup -->|"resolves resume"| node_resume_context
node_live_setup -->|"generates questions"| node_question_agent
node_candidate -->|"answers aloud"| node_live_ui
node_live_ui -.->|"exchanges turns"| node_live_api
node_live_api -->|"runs turn logic"| node_live_graph
node_live_api -->|"transcribes audio"| node_stt
node_live_api -->|"synthesizes speech"| node_tts
node_live_api -.->|"adapts difficulty"| node_difficulty
node_live_api -.->|"checks silence"| node_time_skip
node_live_api -->|"synthesizes report"| node_feedback_agent
node_live_api -->|"persists interview"| node_models
node_candidate -->|"reviews feedback"| node_report_ui
node_candidate -->|"views history"| node_history_ui
node_auth -->|"validates identity"| node_supabase
node_auth -->|"loads user record"| node_db
node_models -->|"uses ORM base"| node_db

click node_resume_ui "https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/resume/resume-upload-flow.tsx"
click node_resume_api "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/resumes.py"
click node_resume_agent "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/resume_parser_agent.py"
click node_resume_context "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/services/resume_context.py"
click node_question_ui "https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/questions/question-bank-view.tsx"
click node_question_api "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/questions.py"
click node_question_agent "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/question_generator_agent.py"
click node_live_setup "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/interview_sessions.py"
click node_live_ui "https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/interview/live-view.tsx"
click node_live_api "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/live_interview.py"
click node_live_graph "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/livegraph.py"
click node_stt "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/services/stt.py"
click node_tts "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/services/tts.py"
click node_difficulty "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/adpative_difficulty_controller.py"
click node_time_skip "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/time_skip_handler.py"
click node_feedback_agent "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/feedback_synthesis_agent.py"
click node_report_ui "https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/interview/report-view.tsx"
click node_history_ui "https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/history/history-view.tsx"
click node_auth "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/cores/auth_dependancy.py"
click node_db "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/cores/database.py"
click node_models "https://github.com/hamza-24-ai/intraai/tree/main/backened/app/models"
click node_supabase "https://github.com/hamza-24-ai/intraai/blob/main/backened/app/cores/supabase_client.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_resume_ui,node_resume_api,node_resume_agent,node_resume_context toneBlue
class node_question_ui,node_question_api,node_question_agent toneAmber
class node_live_setup,node_live_ui,node_live_api,node_live_graph,node_stt,node_tts,node_difficulty,node_time_skip toneMint
class node_feedback_agent,node_report_ui,node_history_ui toneRose
class node_auth,node_db,node_models,node_supabase,node_candidate toneIndigo
```

## Components

### Practice setup

- [Resume upload](https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/resume/resume-upload-flow.tsx): `frontened/components/resume/resume-upload-flow.tsx`
- [Resume handling](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/resumes.py): `backened/app/routers/resumes.py`
- [Resume parser](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/resume_parser_agent.py): `backened/app/agent/resume_parser_agent.py`
- [Resume context](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/services/resume_context.py): `backened/app/services/resume_context.py`

### Question bank

- [Question bank](https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/questions/question-bank-view.tsx): `frontened/components/questions/question-bank-view.tsx`
- [Question generation API](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/questions.py): `backened/app/routers/questions.py`
- [Question generator](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/question_generator_agent.py): `backened/app/agent/question_generator_agent.py`

### Live interview

- [Interview setup](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/interview_sessions.py): `backened/app/routers/interview_sessions.py`
- [Live interview screen](https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/interview/live-view.tsx): `frontened/components/interview/live-view.tsx`
- [Live interview runtime](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/routers/live_interview.py): `backened/app/routers/live_interview.py`
- [Interview agent graph](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/livegraph.py): `backened/app/agent/livegraph.py`
- [Speech recognition](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/services/stt.py): `backened/app/services/stt.py`
- [Speech synthesis](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/services/tts.py): `backened/app/services/tts.py`
- [Difficulty controller](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/adpative_difficulty_controller.py): `backened/app/agent/adpative_difficulty_controller.py`
- [Silence handler](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/time_skip_handler.py): `backened/app/agent/time_skip_handler.py`

### Reports and history

- [Feedback synthesis](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/agent/feedback_synthesis_agent.py): `backened/app/agent/feedback_synthesis_agent.py`
- [Report view](https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/interview/report-view.tsx): `frontened/components/interview/report-view.tsx`
- [History view](https://github.com/hamza-24-ai/intraai/blob/main/frontened/components/history/history-view.tsx): `frontened/components/history/history-view.tsx`

### Platform services

- [Authentication](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/cores/auth_dependancy.py): `backened/app/cores/auth_dependancy.py`
- [Relational database](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/cores/database.py): `backened/app/cores/database.py`
- [Product records](https://github.com/hamza-24-ai/intraai/tree/main/backened/app/models): `backened/app/models`
- [Supabase auth](https://github.com/hamza-24-ai/intraai/blob/main/backened/app/cores/supabase_client.py): `backened/app/cores/supabase_client.py`

### Other components

- **Candidate**

## Connections

- Candidate → Resume upload: uploads resume
- Resume upload → Resume handling: submits resume
- Resume handling → Resume parser: parses resume
- Resume handling → Resume context: resolves skills
- Candidate → Question bank: studies questions
- Question generation API → Question generator: generates questions
- Candidate → Interview setup: starts interview
- Interview setup → Resume context: resolves resume (evidence: `backened/app/routers/interview_sessions.py`)
- Interview setup → Question generator: generates questions (evidence: `backened/app/routers/interview_sessions.py`)
- Candidate → Live interview screen: answers aloud
- Live interview screen → Live interview runtime: exchanges turns
- Live interview runtime → Interview agent graph: runs turn logic (evidence: `backened/app/routers/live_interview.py`)
- Live interview runtime → Speech recognition: transcribes audio (evidence: `backened/app/routers/live_interview.py`)
- Live interview runtime → Speech synthesis: synthesizes speech (evidence: `backened/app/routers/live_interview.py`)
- Live interview runtime → Difficulty controller: adapts difficulty
- Live interview runtime → Silence handler: checks silence
- Live interview runtime → Feedback synthesis: synthesizes report (evidence: `backened/app/routers/live_interview.py`)
- Live interview runtime → Product records: persists interview (evidence: `backened/app/routers/live_interview.py`)
- Candidate → Report view: reviews feedback
- Candidate → History view: views history
- Authentication → Supabase auth: validates identity (evidence: `backened/app/cores/auth_dependancy.py`)
- Authentication → Relational database: loads user record (evidence: `backened/app/cores/auth_dependancy.py`)
- Product records → Relational database: uses ORM base (evidence: `backened/app/models/interview_sessions.py`)
