# mbessalle/ai-interviewer architecture

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

## Overview

AI Interviewer is a hiring product: recruiters configure interviews and share candidate links; candidates complete account-free voice interviews, after which recruiters review transcripts, scores, communication analysis, and cross-candidate insights. The graph follows question generation, interview setup, call registration and completion, analysis, and dashboard review, alongside the trace-recording layer. README documents the end-to-end flow and major AI capabilities; source excerpts confirm selected route, database, and tracing calls. Other API and UI relationships are based on the documented workflow, not inspected component source.

Main entry points: [`src/app/api/register-call/route.ts`](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/register-call/route.ts) (Call Registration), [`src/db/queries/responses.ts`](https://github.com/mbessalle/ai-interviewer/blob/main/src/db/queries/responses.ts) (Response Queries), [`src/app/(client)/dashboard/page.tsx`](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/(client)/dashboard/page.tsx) (Recruiter Dashboard), [`src/lib/llm/chat.ts`](https://github.com/mbessalle/ai-interviewer/blob/main/src/lib/llm/chat.ts) (Validated LLM)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_setup["Recruiter Setup"]
  node_dashboard["Recruiter Dashboard<br/>[page.tsx]"]
  node_interview_details["Interview Details<br/>[page.tsx]"]
  node_question_api["Question Generation<br/>[route.ts]"]
  node_interviewer_api["Interviewer Setup<br/>[route.ts]"]
end

subgraph group_voice["Candidate Voice Interview"]
  node_candidate_page["Candidate Link<br/>[page.tsx]"]
  node_call_interface["Voice Call Interface"]
  node_register_call["Call Registration<br/>[route.ts]"]
  node_webhook["Call Webhook<br/>[route.ts]"]
end

subgraph group_analysis["AI Analysis"]
  node_llm_helper["Validated LLM<br/>[chat.ts]"]
  node_communication["Communication Analysis<br/>[route.ts]"]
  node_insights["Candidate Insights<br/>[route.ts]"]
  node_analytics["Response Analytics"]
end

subgraph group_storage["Data and Access"]
  node_interviewer_store["Interviewer Queries<br/>[interviewers.ts]"]
  node_interview_queries["Interview Queries<br/>[interviews.ts]"]
  node_response_queries["Response Queries<br/>[responses.ts]"]
  node_postgres[("Postgres Records<br/>[schema.ts]")]
  node_actions["Server Actions"]
  node_access["Access Rules<br/>[access.ts]"]
end

subgraph group_observability["Tracing"]
  node_trace_routes["Route Tracing<br/>[route.ts]"]
  node_trace_record["Trace Recorder<br/>[record.ts]"]
  node_trace_events[("Trace Events<br/>[schema.ts]")]
end

node_recruiter(("Recruiter"))
node_candidate(("Candidate"))
node_openai{{"OpenAI"}}
node_retell{{"Retell Voice"}}

node_recruiter -->|"manages interviews"| node_dashboard
node_dashboard -->|"requests questions"| node_question_api
node_question_api -->|"validates model reply"| node_llm_helper
node_llm_helper -->|"calls model"| node_openai
node_dashboard -.->|"creates interviewers"| node_interviewer_api
node_interviewer_api -->|"reads and writes"| node_interviewer_store
node_interview_details -->|"shares interview link"| node_candidate_page
node_candidate -->|"opens link"| node_candidate_page
node_candidate_page -.->|"starts interview"| node_call_interface
node_call_interface -->|"registers call"| node_register_call
node_register_call -->|"loads interview"| node_interview_queries
node_register_call -->|"loads interviewer"| node_interviewer_store
node_register_call -->|"creates web call"| node_retell
node_retell -->|"conducts voice call"| node_candidate
node_retell -->|"posts call result"| node_webhook
node_webhook -.->|"records response"| node_response_queries
node_webhook -.->|"triggers analysis"| node_communication
node_communication -->|"validates analysis"| node_llm_helper
node_communication -.->|"stores analysis"| node_response_queries
node_insights -->|"loads responses"| node_response_queries
node_insights -->|"loads and updates interview"| node_interview_queries
node_insights -->|"validates insights"| node_llm_helper
node_dashboard -.->|"views call results"| node_analytics
node_analytics -->|"reads responses"| node_response_queries
node_actions -->|"checks permissions"| node_access
node_actions -.->|"reads and writes"| node_interview_queries
node_interview_queries -->|"queries records"| node_postgres
node_response_queries -.->|"queries records"| node_postgres
node_trace_routes -->|"records route"| node_trace_record
node_trace_record -->|"persists trace steps"| node_trace_events
node_trace_record -->|"writes SQL traces"| node_postgres
node_question_api -.->|"wraps route"| node_trace_routes
node_register_call -->|"wraps route"| node_trace_routes

click node_dashboard "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/(client)/dashboard/page.tsx"
click node_interview_details "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/(client)/interviews/%5BinterviewId%5D/page.tsx"
click node_question_api "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/generate-interview-questions/route.ts"
click node_llm_helper "https://github.com/mbessalle/ai-interviewer/blob/main/src/lib/llm/chat.ts"
click node_interviewer_api "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/create-interviewer/route.ts"
click node_interviewer_store "https://github.com/mbessalle/ai-interviewer/blob/main/src/db/queries/interviewers.ts"
click node_candidate_page "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/(user)/call/%5BinterviewId%5D/page.tsx"
click node_call_interface "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/(user)/call/%5BinterviewId%5D/interview-interface.tsx"
click node_register_call "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/register-call/route.ts"
click node_webhook "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/response-webhook/route.ts"
click node_communication "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/analyze-communication/route.ts"
click node_insights "https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/generate-insights/route.ts"
click node_analytics "https://github.com/mbessalle/ai-interviewer/blob/main/src/services/analytics.service.ts"
click node_interview_queries "https://github.com/mbessalle/ai-interviewer/blob/main/src/db/queries/interviews.ts"
click node_response_queries "https://github.com/mbessalle/ai-interviewer/blob/main/src/db/queries/responses.ts"
click node_postgres "https://github.com/mbessalle/ai-interviewer/blob/main/src/db/schema.ts"
click node_actions "https://github.com/mbessalle/ai-interviewer/blob/main/src/services/interviews.actions.ts"
click node_access "https://github.com/mbessalle/ai-interviewer/blob/main/src/lib/access.ts"
click node_trace_routes "https://github.com/mbessalle/ai-interviewer/blob/main/src/lib/trace/route.ts"
click node_trace_record "https://github.com/mbessalle/ai-interviewer/blob/main/src/lib/trace/record.ts"
click node_trace_events "https://github.com/mbessalle/ai-interviewer/blob/main/src/db/schema.ts"

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_interview_details,node_question_api,node_interviewer_api toneBlue
class node_candidate_page,node_call_interface,node_register_call,node_webhook toneAmber
class node_llm_helper,node_communication,node_insights,node_analytics toneMint
class node_interviewer_store,node_interview_queries,node_response_queries,node_postgres,node_actions,node_access toneRose
class node_trace_routes,node_trace_record,node_trace_events,node_recruiter,node_candidate,node_openai,node_retell toneIndigo
```

## Components

### Recruiter Setup

- [Recruiter Dashboard](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/(client)/dashboard/page.tsx): `src/app/(client)/dashboard/page.tsx`
- [Interview Details](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/(client)/interviews/%5BinterviewId%5D/page.tsx): `src/app/(client)/interviews/[interviewId]/page.tsx`
- [Question Generation](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/generate-interview-questions/route.ts): `src/app/api/generate-interview-questions/route.ts`
- [Interviewer Setup](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/create-interviewer/route.ts): `src/app/api/create-interviewer/route.ts`

### Candidate Voice Interview

- [Candidate Link](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/(user)/call/%5BinterviewId%5D/page.tsx): `src/app/(user)/call/[interviewId]/page.tsx`
- [Voice Call Interface](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/(user)/call/%5BinterviewId%5D/interview-interface.tsx): `src/app/(user)/call/[interviewId]/interview-interface.tsx`
- [Call Registration](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/register-call/route.ts): `src/app/api/register-call/route.ts`
- [Call Webhook](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/response-webhook/route.ts): `src/app/api/response-webhook/route.ts`

### AI Analysis

- [Validated LLM](https://github.com/mbessalle/ai-interviewer/blob/main/src/lib/llm/chat.ts): `src/lib/llm/chat.ts`
- [Communication Analysis](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/analyze-communication/route.ts): `src/app/api/analyze-communication/route.ts`
- [Candidate Insights](https://github.com/mbessalle/ai-interviewer/blob/main/src/app/api/generate-insights/route.ts): `src/app/api/generate-insights/route.ts`
- [Response Analytics](https://github.com/mbessalle/ai-interviewer/blob/main/src/services/analytics.service.ts): `src/services/analytics.service.ts`

### Data and Access

- [Interviewer Queries](https://github.com/mbessalle/ai-interviewer/blob/main/src/db/queries/interviewers.ts): `src/db/queries/interviewers.ts`
- [Interview Queries](https://github.com/mbessalle/ai-interviewer/blob/main/src/db/queries/interviews.ts): `src/db/queries/interviews.ts`
- [Response Queries](https://github.com/mbessalle/ai-interviewer/blob/main/src/db/queries/responses.ts): `src/db/queries/responses.ts`
- [Postgres Records](https://github.com/mbessalle/ai-interviewer/blob/main/src/db/schema.ts): `src/db/schema.ts`
- [Server Actions](https://github.com/mbessalle/ai-interviewer/blob/main/src/services/interviews.actions.ts): `src/services/interviews.actions.ts`
- [Access Rules](https://github.com/mbessalle/ai-interviewer/blob/main/src/lib/access.ts): `src/lib/access.ts`

### Tracing

- [Route Tracing](https://github.com/mbessalle/ai-interviewer/blob/main/src/lib/trace/route.ts): `src/lib/trace/route.ts`
- [Trace Recorder](https://github.com/mbessalle/ai-interviewer/blob/main/src/lib/trace/record.ts): `src/lib/trace/record.ts`
- [Trace Events](https://github.com/mbessalle/ai-interviewer/blob/main/src/db/schema.ts): `src/db/schema.ts`

### Other components

- **Recruiter**
- **Candidate**
- **OpenAI**
- **Retell Voice**

## Connections

- Recruiter → Recruiter Dashboard: manages interviews
- Recruiter Dashboard → Question Generation: requests questions
- Question Generation → Validated LLM: validates model reply (evidence: `src/app/api/generate-interview-questions/route.ts`)
- Validated LLM → OpenAI: calls model
- Recruiter Dashboard → Interviewer Setup: creates interviewers
- Interviewer Setup → Interviewer Queries: reads and writes (evidence: `src/app/api/create-interviewer/route.ts`)
- Interview Details → Candidate Link: shares interview link
- Candidate → Candidate Link: opens link
- Candidate Link → Voice Call Interface: starts interview
- Voice Call Interface → Call Registration: registers call
- Call Registration → Interview Queries: loads interview (evidence: `src/app/api/register-call/route.ts`)
- Call Registration → Interviewer Queries: loads interviewer (evidence: `src/app/api/register-call/route.ts`)
- Call Registration → Retell Voice: creates web call (evidence: `src/app/api/register-call/route.ts`)
- Retell Voice → Candidate: conducts voice call
- Retell Voice → Call Webhook: posts call result
- Call Webhook → Response Queries: records response
- Call Webhook → Communication Analysis: triggers analysis
- Communication Analysis → Validated LLM: validates analysis (evidence: `src/app/api/analyze-communication/route.ts`)
- Communication Analysis → Response Queries: stores analysis
- Candidate Insights → Response Queries: loads responses (evidence: `src/app/api/generate-insights/route.ts`)
- Candidate Insights → Interview Queries: loads and updates interview (evidence: `src/app/api/generate-insights/route.ts`)
- Candidate Insights → Validated LLM: validates insights (evidence: `src/app/api/generate-insights/route.ts`)
- Recruiter Dashboard → Response Analytics: views call results
- Response Analytics → Response Queries: reads responses (evidence: `src/app/api/get-call/route.ts`)
- Server Actions → Access Rules: checks permissions
- Server Actions → Interview Queries: reads and writes
- Interview Queries → Postgres Records: queries records (evidence: `src/db/queries/interviews.ts`)
- Response Queries → Postgres Records: queries records (evidence: `src/db/queries/responses.ts`)
- Route Tracing → Trace Recorder: records route (evidence: `src/lib/trace/route.ts`)
- Trace Recorder → Trace Events: persists trace steps (evidence: `src/lib/trace/record.ts`)
- Trace Recorder → Postgres Records: writes SQL traces (evidence: `src/lib/trace/record.ts`)
- Question Generation → Route Tracing: wraps route (evidence: `src/app/api/generate-interview-questions/route.ts`)
- Call Registration → Route Tracing: wraps route (evidence: `src/app/api/register-call/route.ts`)
