# pavankl24/ai_interview_agent architecture

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

- Interactive diagram: https://gitdiagram.com/pavankl24/ai_interview_agent
- Repository: https://github.com/pavankl24/ai_interview_agent

## Overview

COGNIV AI is a technical interview practice platform. Candidates configure an interview, answer adaptive AI-generated questions, and receive a final report saved for later review; they can also build a personalized learning roadmap from interview results. The graph includes the React client, FastAPI interview and learning flows, AI/reporting, and persistence. README capabilities such as Judge0 code execution and Supabase authentication are included; their detailed wiring is not fully shown in sampled source, so those links are documented or marked optional.

Main entry points: [`web/src/App.tsx`](https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/App.tsx) (Interview workspace), [`api.py`](https://github.com/pavankl24/ai_interview_agent/blob/main/api.py) (Interview orchestration), [`database.py`](https://github.com/pavankl24/ai_interview_agent/blob/main/database.py) (Interview persistence), [`backend/services/learning_service.py`](https://github.com/pavankl24/ai_interview_agent/blob/main/backend/services/learning_service.py) (Roadmap generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Candidate experience"]
  node_app["Interview workspace<br/>[App.tsx]"]
  node_api_client["HTTP client<br/>[apiClient.ts]"]
  node_speech["Speech input"]
  node_timer["Question timer<br/>[useCountdown.ts]"]
  node_copy["Copy utility"]
  node_roadmap_ui["Roadmap interface"]
end

subgraph group_interview["Interview services"]
  node_backend_entry["API assembly<br/>[main.py]"]
  node_interview_api["Interview orchestration<br/>[api.py]"]
  node_interview_router["Interview routes<br/>[interview.py]"]
  node_agent_facade["Agent facade<br/>[agent.py]"]
  node_ai_agent["Adaptive interviewer<br/>[ai_service.py]"]
  node_report["Performance report<br/>[report.py]"]
end

subgraph group_learning["Learning roadmap"]
  node_learning_router["Learning routes<br/>[learning.py]"]
  node_learning_service["Roadmap generation"]
end

subgraph group_platform["Identity and persistence"]
  node_supabase_client["Supabase client<br/>[supabase.ts]"]
  node_session_store["Session storage<br/>[session_store.py]"]
  node_database[("Interview persistence<br/>[database.py]")]
end

node_candidate(("Candidate"))
node_groq["Groq LLM"]
node_supabase[("Supabase services")]
node_judge0["Judge0 executor"]

node_candidate -->|"configures and answers"| node_app
node_app -->|"sends requests"| node_api_client
node_app -->|"uses speech input"| node_speech
node_app -->|"uses countdown"| node_timer
node_app -->|"uses copy"| node_copy
node_app -->|"renders roadmap"| node_roadmap_ui
node_app -->|"uses authentication"| node_supabase_client
node_api_client -->|"calls API"| node_backend_entry
node_backend_entry -->|"mounts routes"| node_interview_router
node_backend_entry -->|"mounts routes"| node_learning_router
node_interview_router -->|"uses interviewer"| node_ai_agent
node_interview_api -->|"creates agent"| node_agent_facade
node_agent_facade -->|"re-exports"| node_ai_agent
node_interview_api -->|"generates report"| node_report
node_interview_api -->|"loads and saves sessions"| node_session_store
node_interview_api -->|"reads history"| node_database
node_ai_agent -->|"requests completions"| node_groq
node_report -->|"generates evaluation"| node_groq
node_report -.->|"report persistence"| node_database
node_learning_router -->|"dispatches requests"| node_learning_service
node_learning_router -->|"verifies identity"| node_database
node_learning_service -->|"reads interview reports"| node_database
node_learning_service -->|"generates learning content"| node_groq
node_roadmap_ui -.->|"requests roadmap"| node_api_client
node_database -->|"stores sessions"| node_supabase
node_supabase_client -->|"authenticates users"| node_supabase
node_app -->|"submits code"| node_interview_api
node_interview_api -->|"dispatches execution"| node_judge0
node_learning_service -.->|"validates exercises"| node_judge0

click node_app "https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/App.tsx"
click node_api_client "https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/apiClient.ts"
click node_speech "https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/hooks/useSpeechRecognition.ts"
click node_timer "https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/hooks/useCountdown.ts"
click node_copy "https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/hooks/useCopyToClipboard.ts"
click node_roadmap_ui "https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/LearningRoadmap.tsx"
click node_backend_entry "https://github.com/pavankl24/ai_interview_agent/blob/main/backend/main.py"
click node_interview_api "https://github.com/pavankl24/ai_interview_agent/blob/main/api.py"
click node_interview_router "https://github.com/pavankl24/ai_interview_agent/blob/main/backend/routers/interview.py"
click node_agent_facade "https://github.com/pavankl24/ai_interview_agent/blob/main/agent.py"
click node_ai_agent "https://github.com/pavankl24/ai_interview_agent/blob/main/backend/services/ai_service.py"
click node_report "https://github.com/pavankl24/ai_interview_agent/blob/main/report.py"
click node_learning_router "https://github.com/pavankl24/ai_interview_agent/blob/main/backend/routers/learning.py"
click node_learning_service "https://github.com/pavankl24/ai_interview_agent/blob/main/backend/services/learning_service.py"
click node_supabase_client "https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/supabase.ts"
click node_session_store "https://github.com/pavankl24/ai_interview_agent/blob/main/backend/services/session_store.py"
click node_database "https://github.com/pavankl24/ai_interview_agent/blob/main/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_app,node_api_client,node_speech,node_timer,node_copy,node_roadmap_ui toneBlue
class node_backend_entry,node_interview_api,node_interview_router,node_agent_facade,node_ai_agent,node_report,node_supabase toneAmber
class node_learning_router,node_learning_service toneMint
class node_supabase_client,node_session_store,node_database toneRose
class node_candidate,node_groq,node_judge0 toneIndigo
```

## Components

### Candidate experience

- [Interview workspace](https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [HTTP client](https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/apiClient.ts): `web/src/apiClient.ts`
- [Speech input](https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/hooks/useSpeechRecognition.ts): `web/src/hooks/useSpeechRecognition.ts`
- [Question timer](https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/hooks/useCountdown.ts): `web/src/hooks/useCountdown.ts`
- [Copy utility](https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/hooks/useCopyToClipboard.ts): `web/src/hooks/useCopyToClipboard.ts`
- [Roadmap interface](https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/LearningRoadmap.tsx): `web/src/LearningRoadmap.tsx`

### Interview services

- [API assembly](https://github.com/pavankl24/ai_interview_agent/blob/main/backend/main.py): `backend/main.py`
- [Interview orchestration](https://github.com/pavankl24/ai_interview_agent/blob/main/api.py): `api.py`
- [Interview routes](https://github.com/pavankl24/ai_interview_agent/blob/main/backend/routers/interview.py): `backend/routers/interview.py`
- [Agent facade](https://github.com/pavankl24/ai_interview_agent/blob/main/agent.py): `agent.py`
- [Adaptive interviewer](https://github.com/pavankl24/ai_interview_agent/blob/main/backend/services/ai_service.py): `backend/services/ai_service.py`
- [Performance report](https://github.com/pavankl24/ai_interview_agent/blob/main/report.py): `report.py`

### Learning roadmap

- [Learning routes](https://github.com/pavankl24/ai_interview_agent/blob/main/backend/routers/learning.py): `backend/routers/learning.py`
- [Roadmap generation](https://github.com/pavankl24/ai_interview_agent/blob/main/backend/services/learning_service.py): `backend/services/learning_service.py`

### Identity and persistence

- [Supabase client](https://github.com/pavankl24/ai_interview_agent/blob/main/web/src/supabase.ts): `web/src/supabase.ts`
- [Session storage](https://github.com/pavankl24/ai_interview_agent/blob/main/backend/services/session_store.py): `backend/services/session_store.py`
- [Interview persistence](https://github.com/pavankl24/ai_interview_agent/blob/main/database.py): `database.py`

### Other components

- **Candidate**
- **Groq LLM**
- **Supabase services**
- **Judge0 executor**

## Connections

- Candidate → Interview workspace: configures and answers (evidence: `Readme.md`)
- Interview workspace → HTTP client: sends requests (evidence: `web/src/App.tsx`)
- Interview workspace → Speech input: uses speech input (evidence: `web/src/App.tsx`)
- Interview workspace → Question timer: uses countdown (evidence: `web/src/App.tsx`)
- Interview workspace → Copy utility: uses copy (evidence: `web/src/App.tsx`)
- Interview workspace → Roadmap interface: renders roadmap (evidence: `web/src/App.tsx`)
- Interview workspace → Supabase client: uses authentication (evidence: `web/src/App.tsx`)
- HTTP client → API assembly: calls API (evidence: `Readme.md`)
- API assembly → Interview routes: mounts routes (evidence: `backend/main.py`)
- API assembly → Learning routes: mounts routes (evidence: `backend/main.py`)
- Interview routes → Adaptive interviewer: uses interviewer (evidence: `backend/routers/interview.py`)
- Interview orchestration → Agent facade: creates agent (evidence: `api.py`)
- Agent facade → Adaptive interviewer: re-exports (evidence: `agent.py`)
- Interview orchestration → Performance report: generates report (evidence: `api.py`)
- Interview orchestration → Session storage: loads and saves sessions (evidence: `api.py`)
- Interview orchestration → Interview persistence: reads history (evidence: `api.py`)
- Adaptive interviewer → Groq LLM: requests completions (evidence: `Readme.md`)
- Performance report → Groq LLM: generates evaluation (evidence: `report.py`)
- Performance report → Interview persistence: report persistence
- Learning routes → Roadmap generation: dispatches requests (evidence: `backend/routers/learning.py`)
- Learning routes → Interview persistence: verifies identity (evidence: `backend/routers/learning.py`)
- Roadmap generation → Interview persistence: reads interview reports (evidence: `backend/services/learning_service.py`)
- Roadmap generation → Groq LLM: generates learning content (evidence: `Readme.md`)
- Roadmap interface → HTTP client: requests roadmap
- Interview persistence → Supabase services: stores sessions (evidence: `Readme.md`)
- Supabase client → Supabase services: authenticates users (evidence: `Readme.md`)
- Interview workspace → Interview orchestration: submits code (evidence: `Readme.md`)
- Interview orchestration → Judge0 executor: dispatches execution (evidence: `Readme.md`)
- Roadmap generation → Judge0 executor: validates exercises
