# udayteja21/intellihire-ai architecture

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

- Interactive diagram: https://gitdiagram.com/udayteja21/intellihire-ai
- Repository: https://github.com/udayteja21/intellihire-ai

## Overview

IntelliHire AI is a candidate coaching platform: users create accounts, analyze resumes, practice mock interviews, and review readiness feedback and progress. The frontend’s feature pages use a shared API client to reach FastAPI; API routes coordinate analysis, interview state, and reports. Authentication, persistent records, AI generation/evaluation, speech transcription, and emailed/PDF reports are distinct supporting stages. The routes excerpt and service files support the backend links shown; frontend page-to-API wiring and unsampled AI orchestration details are not shown, so those links are kept at the shared-client level.

Main entry points: [`backend/app/services/ai/core.py`](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/core.py) (AI orchestration), [`frontend/src/lib/api.js`](https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/lib/api.js) (API client), [`backend/app/api/routes.py`](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/api/routes.py) (Product API routes), [`backend/app/api/auth.py`](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/api/auth.py) (Auth endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Candidate experience"]
  node_resume["Resume analysis<br/>[page.js]"]
  node_interview["Mock interview<br/>[page.js]"]
  node_history["Practice history<br/>[page.js]"]
  node_reports["Readiness reports<br/>[page.js]"]
  node_materials["Learning materials<br/>[page.js]"]
  node_authui["Account access<br/>[page.js]"]
  node_apiclient["API client<br/>[api.js]"]
end

subgraph group_api["API and identity"]
  node_server["FastAPI app<br/>[main.py]"]
  node_authroutes["Auth endpoints<br/>[auth.py]"]
  node_routes["Product API routes<br/>[routes.py]"]
  node_security["Token security<br/>[security.py]"]
end

subgraph group_coaching["AI coaching"]
  node_ai["AI orchestration<br/>[core.py]"]
  node_parser["AI parsing<br/>[parser.py]"]
  node_validator["AI validation<br/>[validator.py]"]
  node_fallback["Fallback analysis"]
  node_gemini["Gemini provider<br/>[gemini_service.py]"]
  node_groq["Groq provider<br/>[groq_service.py]"]
  node_openrouter["OpenRouter provider"]
end

subgraph group_records["Candidate records"]
  node_database[("Application database<br/>[database.py]")]
  node_models["User and sessions<br/>[models.py]"]
  node_pdf["Interview PDF<br/>[pdf_service.py]"]
  node_email["Email notifications<br/>[email_service.py]"]
end

node_candidate(("Candidate"))
node_llmservice{{"LLM APIs"}}
node_smtp{{"SMTP service"}}

node_candidate -->|"submits resume"| node_resume
node_candidate -->|"practices"| node_interview
node_candidate -->|"signs in"| node_authui
node_resume -->|"requests analysis"| node_apiclient
node_interview -->|"requests session"| node_apiclient
node_history -->|"loads history"| node_apiclient
node_reports -->|"loads reports"| node_apiclient
node_materials -->|"loads resources"| node_apiclient
node_authui -->|"sends credentials"| node_apiclient
node_apiclient -->|"HTTP requests"| node_server
node_server -->|"mounts auth"| node_authroutes
node_server -->|"mounts APIs"| node_routes
node_authroutes -->|"queries and updates"| node_database
node_authroutes -->|"hashes and signs"| node_security
node_authroutes -->|"sends account email"| node_email
node_routes -->|"reads and writes"| node_database
node_routes -->|"requests analysis"| node_ai
node_routes -->|"transcribes audio"| node_groq
node_routes -->|"generates report"| node_pdf
node_routes -->|"sends completion email"| node_email
node_database -->|"maps records"| node_models
node_ai -->|"parses output"| node_parser
node_ai -->|"validates output"| node_validator
node_ai -->|"uses fallback"| node_fallback
node_ai -->|"generates content"| node_gemini
node_ai -->|"generates content"| node_groq
node_ai -->|"generates content"| node_openrouter
node_gemini -->|"calls provider"| node_llmservice
node_groq -->|"calls provider"| node_llmservice
node_openrouter -->|"calls provider"| node_llmservice
node_email -->|"sends mail"| node_smtp

click node_resume "https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/resume/page.js"
click node_interview "https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/interview/page.js"
click node_history "https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/history/page.js"
click node_reports "https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/reports/page.js"
click node_materials "https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/materials/page.js"
click node_authui "https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/login/page.js"
click node_apiclient "https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/lib/api.js"
click node_server "https://github.com/udayteja21/intellihire-ai/blob/main/backend/main.py"
click node_authroutes "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/api/auth.py"
click node_routes "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/api/routes.py"
click node_security "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/core/security.py"
click node_ai "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/core.py"
click node_parser "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/parser.py"
click node_validator "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/validator.py"
click node_fallback "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/fallback_service.py"
click node_gemini "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/gemini_service.py"
click node_groq "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/groq_service.py"
click node_openrouter "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/openrouter_service.py"
click node_database "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/db/database.py"
click node_models "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/db/models.py"
click node_pdf "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/pdf_service.py"
click node_email "https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/email_service.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,node_interview,node_history,node_reports,node_materials,node_authui,node_apiclient toneBlue
class node_server,node_authroutes,node_routes,node_security toneAmber
class node_ai,node_parser,node_validator,node_fallback,node_gemini,node_groq,node_openrouter,node_llmservice toneMint
class node_database,node_models,node_pdf,node_email toneRose
class node_candidate,node_smtp toneIndigo
```

## Components

### Candidate experience

- [Resume analysis](https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/resume/page.js): `frontend/src/app/resume/page.js`
- [Mock interview](https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/interview/page.js): `frontend/src/app/interview/page.js`
- [Practice history](https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/history/page.js): `frontend/src/app/history/page.js`
- [Readiness reports](https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/reports/page.js): `frontend/src/app/reports/page.js`
- [Learning materials](https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/materials/page.js): `frontend/src/app/materials/page.js`
- [Account access](https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/app/login/page.js): `frontend/src/app/login/page.js`
- [API client](https://github.com/udayteja21/intellihire-ai/blob/main/frontend/src/lib/api.js): `frontend/src/lib/api.js`

### API and identity

- [FastAPI app](https://github.com/udayteja21/intellihire-ai/blob/main/backend/main.py): `backend/main.py`
- [Auth endpoints](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/api/auth.py): `backend/app/api/auth.py`
- [Product API routes](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/api/routes.py): `backend/app/api/routes.py`
- [Token security](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/core/security.py): `backend/app/core/security.py`

### AI coaching

- [AI orchestration](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/core.py): `backend/app/services/ai/core.py`
- [AI parsing](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/parser.py): `backend/app/services/ai/parser.py`
- [AI validation](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/validator.py): `backend/app/services/ai/validator.py`
- [Fallback analysis](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/fallback_service.py): `backend/app/services/ai/fallback_service.py`
- [Gemini provider](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/gemini_service.py): `backend/app/services/ai/gemini_service.py`
- [Groq provider](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/groq_service.py): `backend/app/services/ai/groq_service.py`
- [OpenRouter provider](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/ai/openrouter_service.py): `backend/app/services/ai/openrouter_service.py`

### Candidate records

- [Application database](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/db/database.py): `backend/app/db/database.py`
- [User and sessions](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Interview PDF](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/pdf_service.py): `backend/app/services/pdf_service.py`
- [Email notifications](https://github.com/udayteja21/intellihire-ai/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`

### Other components

- **Candidate**
- **LLM APIs**
- **SMTP service**

## Connections

- Candidate → Resume analysis: submits resume
- Candidate → Mock interview: practices
- Candidate → Account access: signs in
- Resume analysis → API client: requests analysis
- Mock interview → API client: requests session
- Practice history → API client: loads history
- Readiness reports → API client: loads reports
- Learning materials → API client: loads resources
- Account access → API client: sends credentials
- API client → FastAPI app: HTTP requests
- FastAPI app → Auth endpoints: mounts auth
- FastAPI app → Product API routes: mounts APIs
- Auth endpoints → Application database: queries and updates
- Auth endpoints → Token security: hashes and signs
- Auth endpoints → Email notifications: sends account email
- Product API routes → Application database: reads and writes
- Product API routes → AI orchestration: requests analysis
- Product API routes → Groq provider: transcribes audio
- Product API routes → Interview PDF: generates report
- Product API routes → Email notifications: sends completion email
- Application database → User and sessions: maps records
- AI orchestration → AI parsing: parses output
- AI orchestration → AI validation: validates output
- AI orchestration → Fallback analysis: uses fallback
- AI orchestration → Gemini provider: generates content
- AI orchestration → Groq provider: generates content
- AI orchestration → OpenRouter provider: generates content
- Gemini provider → LLM APIs: calls provider
- Groq provider → LLM APIs: calls provider
- OpenRouter provider → LLM APIs: calls provider
- Email notifications → SMTP service: sends mail