# shubhanshu2006/sensei architecture

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

- Interactive diagram: https://gitdiagram.com/shubhanshu2006/sensei
- Repository: https://github.com/shubhanshu2006/sensei

## Overview

Sensei is an AI interview-practice and candidate-screening platform for candidates, recruiters, and administrators. Candidates apply to jobs or enter practice interviews; recruiters configure openings and review screened applicants, while admins manage users, credits, and the practice catalog. The frontend communicates with an Express API, whose domain services persist platform records and invoke AI capabilities. The README also describes real-time voice interviews and asynchronous resume screening. Some subsystem links below reflect README-level architecture; unsampled implementation details are not asserted.

Main entry points: [`backend/src/services/ai/ScreeningService.ts`](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/ScreeningService.ts) (Resume screening), [`frontend/lib/api/client.ts`](https://github.com/shubhanshu2006/sensei/blob/main/frontend/lib/api/client.ts) (API client), [`backend/src/services/ai/LLMClient.ts`](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/LLMClient.ts) (LLM provider client), [`backend/src/services/ai/AIEngine.ts`](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/AIEngine.ts) (AI orchestration)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User portals"]
  node_candidate["Candidate portal"]
  node_recruiter["Recruiter portal"]
  node_admin["Admin portal"]
  node_live_ui["Live interview UI<br/>[page.tsx]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and domain"]
  node_app["HTTP application<br/>[app.ts]"]
  node_routes["API routes<br/>[index.ts]"]
  node_application_controller["Application handlers"]
  node_application_service["Application domain"]
  node_auth_service["Identity and profiles<br/>[auth.service.ts]"]
end

subgraph group_intelligence["AI and interviews"]
  node_ai_engine["AI orchestration<br/>[AIEngine.ts]"]
  node_interview_graph["Adaptive interview<br/>[InterviewGraph.ts]"]
  node_evaluation["Interview evaluation"]
  node_llm["LLM provider client<br/>[LLMClient.ts]"]
  node_resume_parser["Resume extraction<br/>[ResumeParser.ts]"]
  node_screening["Resume screening"]
end

subgraph group_platform["State and integrations"]
  node_queue["Background jobs"]
  node_websocket["Interview socket server"]
  node_database[("PostgreSQL<br/>[client.ts]")]
  node_storage["Resume object storage<br/>[S3Service.ts]"]
end

node_candidate_actor(("Candidate"))
node_recruiter_actor(("Recruiter"))
node_ai_providers{{"LLM providers"}}

node_candidate_actor -->|"uses"| node_candidate
node_recruiter_actor -->|"uses"| node_recruiter
node_candidate -.->|"requests platform data"| node_api_client
node_recruiter -.->|"requests platform data"| node_api_client
node_admin -.->|"manages platform"| node_api_client
node_live_ui -.->|"interviews in real time"| node_websocket
node_api_client -.->|"calls API"| node_app
node_app -->|"mounts"| node_routes
node_routes -->|"routes applications"| node_application_controller
node_application_controller -->|"calls"| node_application_service
node_application_service -->|"reads and writes"| node_database
node_auth_service -->|"reads and writes"| node_database
node_application_service -.->|"screens applicants"| node_screening
node_screening -.->|"extracts resumes"| node_resume_parser
node_screening -.->|"runs asynchronously"| node_queue
node_screening -.->|"uses resume files"| node_storage
node_ai_engine -->|"runs interview"| node_interview_graph
node_ai_engine -->|"screens candidate"| node_screening
node_interview_graph -.->|"generates interview content"| node_llm
node_evaluation -.->|"evaluates with models"| node_llm
node_ai_engine -.->|"transcribes and generates"| node_llm
node_llm -.->|"invokes models"| node_ai_providers

click node_candidate "https://github.com/shubhanshu2006/sensei/tree/main/frontend/app/(platform)/candidate"
click node_recruiter "https://github.com/shubhanshu2006/sensei/tree/main/frontend/app/(platform)/recruiter"
click node_admin "https://github.com/shubhanshu2006/sensei/tree/main/frontend/app/(platform)/admin"
click node_live_ui "https://github.com/shubhanshu2006/sensei/blob/main/frontend/app/(platform)/interview/%5BsessionId%5D/page.tsx"
click node_api_client "https://github.com/shubhanshu2006/sensei/blob/main/frontend/lib/api/client.ts"
click node_app "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/app.ts"
click node_routes "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/routes/index.ts"
click node_application_controller "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/controllers/applications.controller.ts"
click node_application_service "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/applications.service.ts"
click node_auth_service "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/auth.service.ts"
click node_ai_engine "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/AIEngine.ts"
click node_interview_graph "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/InterviewGraph.ts"
click node_evaluation "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/EvaluationService.ts"
click node_llm "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/LLMClient.ts"
click node_resume_parser "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/ResumeParser.ts"
click node_screening "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/ScreeningService.ts"
click node_queue "https://github.com/shubhanshu2006/sensei/tree/main/backend/src/services/queue"
click node_websocket "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/websocket/InterviewSocketServer.ts"
click node_database "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/database/client.ts"
click node_storage "https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/storage/S3Service.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_candidate,node_recruiter,node_admin,node_live_ui,node_api_client toneBlue
class node_app,node_routes,node_application_controller,node_application_service,node_auth_service toneAmber
class node_ai_engine,node_interview_graph,node_evaluation,node_llm,node_resume_parser,node_screening toneMint
class node_queue,node_websocket,node_database,node_storage toneRose
class node_candidate_actor,node_recruiter_actor,node_ai_providers toneIndigo
```

## Components

### User portals

- [Candidate portal](https://github.com/shubhanshu2006/sensei/tree/main/frontend/app/(platform)/candidate): `frontend/app/(platform)/candidate`
- [Recruiter portal](https://github.com/shubhanshu2006/sensei/tree/main/frontend/app/(platform)/recruiter): `frontend/app/(platform)/recruiter`
- [Admin portal](https://github.com/shubhanshu2006/sensei/tree/main/frontend/app/(platform)/admin): `frontend/app/(platform)/admin`
- [Live interview UI](https://github.com/shubhanshu2006/sensei/blob/main/frontend/app/(platform)/interview/%5BsessionId%5D/page.tsx): `frontend/app/(platform)/interview/[sessionId]/page.tsx`
- [API client](https://github.com/shubhanshu2006/sensei/blob/main/frontend/lib/api/client.ts): `frontend/lib/api/client.ts`

### API and domain

- [HTTP application](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/app.ts): `backend/src/app.ts`
- [API routes](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/routes/index.ts): `backend/src/routes/index.ts`
- [Application handlers](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/controllers/applications.controller.ts): `backend/src/controllers/applications.controller.ts`
- [Application domain](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/applications.service.ts): `backend/src/services/applications.service.ts`
- [Identity and profiles](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/auth.service.ts): `backend/src/services/auth.service.ts`

### AI and interviews

- [AI orchestration](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/AIEngine.ts): `backend/src/services/ai/AIEngine.ts`
- [Adaptive interview](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/InterviewGraph.ts): `backend/src/services/ai/InterviewGraph.ts`
- [Interview evaluation](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/EvaluationService.ts): `backend/src/services/ai/EvaluationService.ts`
- [LLM provider client](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/LLMClient.ts): `backend/src/services/ai/LLMClient.ts`
- [Resume extraction](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/ResumeParser.ts): `backend/src/services/ai/ResumeParser.ts`
- [Resume screening](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/ai/ScreeningService.ts): `backend/src/services/ai/ScreeningService.ts`

### State and integrations

- [Background jobs](https://github.com/shubhanshu2006/sensei/tree/main/backend/src/services/queue): `backend/src/services/queue`
- [Interview socket server](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/websocket/InterviewSocketServer.ts): `backend/src/services/websocket/InterviewSocketServer.ts`
- [PostgreSQL](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/database/client.ts): `backend/src/database/client.ts`
- [Resume object storage](https://github.com/shubhanshu2006/sensei/blob/main/backend/src/services/storage/S3Service.ts): `backend/src/services/storage/S3Service.ts`

### Other components

- **Candidate**
- **Recruiter**
- **LLM providers**

## Connections

- Candidate → Candidate portal: uses
- Recruiter → Recruiter portal: uses
- Candidate portal → API client: requests platform data
- Recruiter portal → API client: requests platform data
- Admin portal → API client: manages platform
- Live interview UI → Interview socket server: interviews in real time
- API client → HTTP application: calls API
- HTTP application → API routes: mounts (evidence: `backend/src/app.ts`)
- API routes → Application handlers: routes applications
- Application handlers → Application domain: calls (evidence: `backend/src/controllers/applications.controller.ts`)
- Application domain → PostgreSQL: reads and writes (evidence: `backend/src/services/applications.service.ts`)
- Identity and profiles → PostgreSQL: reads and writes (evidence: `backend/src/services/auth.service.ts`)
- Application domain → Resume screening: screens applicants
- Resume screening → Resume extraction: extracts resumes
- Resume screening → Background jobs: runs asynchronously
- Resume screening → Resume object storage: uses resume files
- AI orchestration → Adaptive interview: runs interview (evidence: `backend/src/services/ai/AIEngine.ts`)
- AI orchestration → Resume screening: screens candidate (evidence: `backend/src/services/ai/AIEngine.ts`)
- Adaptive interview → LLM provider client: generates interview content
- Interview evaluation → LLM provider client: evaluates with models (evidence: `backend/src/services/ai/EvaluationService.ts`)
- AI orchestration → LLM provider client: transcribes and generates (evidence: `backend/src/services/ai/AIEngine.ts`)
- LLM provider client → LLM providers: invokes models (evidence: `backend/src/services/ai/LLMClient.ts`)
