# pratyushwinorlearn/persona-ai architecture

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

- Interactive diagram: https://gitdiagram.com/pratyushwinorlearn/persona-ai
- Repository: https://github.com/pratyushwinorlearn/persona-ai

## Overview

Persona.ai is a browser-based AI interview simulator. The user configures an interview, then the frontend requests questions and submits answers; backend interview logic uses an LLM to evaluate answers and choose follow-ups, and speech generation supplies audio and lip-sync cues. The frontend presents the interview and debrief, while documented Pixel Streaming connects the browser to the 3D avatar. Authentication and interview history are additional capabilities. Some streaming infrastructure is described only in the README, so those connections are documented rather than verified in sampled implementation excerpts.

Main entry points: [`frontend/src/App.jsx`](https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/App.jsx) (Stage router), [`frontend/src/pages/InterviewRoom.jsx`](https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/pages/InterviewRoom.jsx) (Live interview), [`backend/src/routes/interview.routes.js`](https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/routes/interview.routes.js) (Interview routes), [`frontend/src/services/api.js`](https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/services/api.js) (API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Interview frontend"]
  node_app["Stage router<br/>[App.jsx]"]
  node_start["Interview setup<br/>[StartInterview.jsx]"]
  node_room["Live interview<br/>[InterviewRoom.jsx]"]
  node_summary["Performance debrief<br/>[Summary.jsx]"]
  node_client_api["API client<br/>[api.js]"]
end

subgraph group_server["Backend API"]
  node_api_server["Express server<br/>[index.js]"]
  node_interview_routes["Interview routes"]
end

subgraph group_intelligence["Interview intelligence"]
  node_interview_logic["Interview workflow"]
  node_ai["Question and answer AI<br/>[ai.service.js]"]
  node_speech["Speech and lip-sync<br/>[tts.service.js]"]
end

subgraph group_identity["Identity and history"]
  node_auth_routes["Auth and history<br/>[auth.routes.js]"]
  node_db_client["Prisma client<br/>[prisma.js]"]
  node_database[("Interview database<br/>[schema.prisma]")]
end

subgraph group_streaming["Avatar streaming"]
  node_avatar["Unreal avatar"]
  node_signaling["Pixel Streaming signaling"]
  node_turn{{"Metered TURN/STUN"}}
end

node_candidate(("Candidate"))
node_groq{{"Groq AI"}}
node_resend{{"Resend email"}}
node_speech_services{{"TTS and viseme tools"}}

node_candidate -->|"uses"| node_app
node_app -->|"renders"| node_start
node_start -.->|"requests start"| node_client_api
node_app -->|"renders"| node_room
node_room -->|"requests interview"| node_client_api
node_app -->|"renders"| node_summary
node_summary -->|"requests summary"| node_client_api
node_client_api -.->|"sends API requests"| node_api_server
node_api_server -->|"registers routes"| node_interview_routes
node_api_server -->|"registers routes"| node_auth_routes
node_interview_routes -->|"calls workflow"| node_interview_logic
node_interview_routes -->|"generates speech"| node_speech
node_interview_routes -->|"generates reaction"| node_ai
node_interview_logic -->|"generates and evaluates"| node_ai
node_interview_logic -->|"reads and writes"| node_db_client
node_db_client -.->|"persists records"| node_database
node_ai -->|"prompts"| node_groq
node_speech -->|"synthesizes and aligns"| node_speech_services
node_auth_routes -.->|"reads and writes"| node_db_client
node_auth_routes -->|"sends verification email"| node_resend
node_room -.->|"streams video and cues"| node_avatar
node_room -.->|"exchanges WebRTC signaling"| node_signaling
node_signaling -.->|"negotiates stream"| node_avatar
node_signaling -.->|"uses traversal"| node_turn

click node_app "https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/App.jsx"
click node_start "https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/pages/StartInterview.jsx"
click node_room "https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/pages/InterviewRoom.jsx"
click node_summary "https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/pages/Summary.jsx"
click node_client_api "https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/services/api.js"
click node_api_server "https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/index.js"
click node_interview_routes "https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/routes/interview.routes.js"
click node_auth_routes "https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/routes/auth.routes.js"
click node_interview_logic "https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/services/interview.service.js"
click node_ai "https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/services/ai.service.js"
click node_speech "https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/services/tts.service.js"
click node_db_client "https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/db/prisma.js"
click node_database "https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/prisma/schema.prisma"

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_start,node_room,node_summary,node_client_api toneBlue
class node_api_server,node_interview_routes toneAmber
class node_interview_logic,node_ai,node_speech toneMint
class node_auth_routes,node_db_client,node_database toneRose
class node_avatar,node_signaling,node_turn,node_candidate,node_groq,node_resend,node_speech_services toneIndigo
```

## Components

### Interview frontend

- [Stage router](https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/App.jsx): `frontend/src/App.jsx`
- [Interview setup](https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/pages/StartInterview.jsx): `frontend/src/pages/StartInterview.jsx`
- [Live interview](https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/pages/InterviewRoom.jsx): `frontend/src/pages/InterviewRoom.jsx`
- [Performance debrief](https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/pages/Summary.jsx): `frontend/src/pages/Summary.jsx`
- [API client](https://github.com/pratyushwinorlearn/persona-ai/blob/main/frontend/src/services/api.js): `frontend/src/services/api.js`

### Backend API

- [Express server](https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/index.js): `backend/src/index.js`
- [Interview routes](https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/routes/interview.routes.js): `backend/src/routes/interview.routes.js`

### Interview intelligence

- [Interview workflow](https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/services/interview.service.js): `backend/src/services/interview.service.js`
- [Question and answer AI](https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/services/ai.service.js): `backend/src/services/ai.service.js`
- [Speech and lip-sync](https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/services/tts.service.js): `backend/src/services/tts.service.js`

### Identity and history

- [Auth and history](https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/routes/auth.routes.js): `backend/src/routes/auth.routes.js`
- [Prisma client](https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/src/db/prisma.js): `backend/src/db/prisma.js`
- [Interview database](https://github.com/pratyushwinorlearn/persona-ai/blob/main/backend/prisma/schema.prisma): `backend/prisma/schema.prisma`

### Avatar streaming

- **Unreal avatar**
- **Pixel Streaming signaling**
- **Metered TURN/STUN**

### Other components

- **Candidate**
- **Groq AI**
- **Resend email**
- **TTS and viseme tools**

## Connections

- Candidate → Stage router: uses (evidence: `README.md`)
- Stage router → Interview setup: renders (evidence: `frontend/src/App.jsx`)
- Interview setup → API client: requests start (evidence: `frontend/src/pages/StartInterview.jsx`)
- Stage router → Live interview: renders (evidence: `frontend/src/App.jsx`)
- Live interview → API client: requests interview (evidence: `frontend/src/pages/InterviewRoom.jsx`)
- Stage router → Performance debrief: renders (evidence: `frontend/src/App.jsx`)
- Performance debrief → API client: requests summary (evidence: `frontend/src/pages/Summary.jsx`)
- API client → Express server: sends API requests (evidence: `README.md`)
- Express server → Interview routes: registers routes (evidence: `backend/src/index.js`)
- Express server → Auth and history: registers routes (evidence: `backend/src/index.js`)
- Interview routes → Interview workflow: calls workflow (evidence: `backend/src/routes/interview.routes.js`)
- Interview routes → Speech and lip-sync: generates speech (evidence: `backend/src/routes/interview.routes.js`)
- Interview routes → Question and answer AI: generates reaction (evidence: `backend/src/routes/interview.routes.js`)
- Interview workflow → Question and answer AI: generates and evaluates (evidence: `backend/src/services/interview.service.js`)
- Interview workflow → Prisma client: reads and writes (evidence: `backend/src/services/interview.service.js`)
- Prisma client → Interview database: persists records
- Question and answer AI → Groq AI: prompts (evidence: `README.md`)
- Speech and lip-sync → TTS and viseme tools: synthesizes and aligns (evidence: `backend/src/services/tts.service.js`)
- Auth and history → Prisma client: reads and writes
- Auth and history → Resend email: sends verification email (evidence: `backend/src/routes/auth.routes.js`)
- Live interview → Unreal avatar: streams video and cues (evidence: `README.md`)
- Live interview → Pixel Streaming signaling: exchanges WebRTC signaling (evidence: `README.md`)
- Pixel Streaming signaling → Unreal avatar: negotiates stream (evidence: `README.md`)
- Pixel Streaming signaling → Metered TURN/STUN: uses traversal (evidence: `README.md`)