# manish-joshi1/ai-recruitment-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/manish-joshi1/ai-recruitment-assistant
- Repository: https://github.com/manish-joshi1/ai-recruitment-assistant

## Overview

AI-Recruitment-Assistant is a web application for collecting job and candidate materials, generating candidate-to-role scorecards, and asking questions about a scorecard. The visible workflow runs from the React home page through API calls to Django endpoints, then into AI extraction and scorecard calculation backed by recruitment records; users can review results and open a candidate chat. The source excerpts support the main scoring and transcript-analysis links, but do not expose all endpoint routing or chat orchestration, so those connections are left unasserted or marked unverified.

Main entry points: [`frontend/src/App.tsx`](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/App.tsx) (App routing), [`backend/recruitment/views.py`](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/views.py) (Django endpoints), [`frontend/src/services/api.ts`](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/services/api.ts) (API client), [`frontend/src/pages/HomePage.tsx`](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/pages/HomePage.tsx) (Workflow home)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Recruiter interface"]
  node_app["App routing<br/>[App.tsx]"]
  node_home["Workflow home<br/>[HomePage.tsx]"]
  node_upload["File upload<br/>[FileUpload.tsx]"]
  node_scorecardlist["Scorecard list<br/>[ScorecardList.tsx]"]
  node_scorecardpage["Scorecard view<br/>[ScorecardPage.tsx]"]
  node_chatpage["Candidate chat<br/>[ChatPage.tsx]"]
  node_header["Header<br/>[Header.tsx]"]
end

subgraph group_api["Application API"]
  node_clientapi["API client<br/>[api.ts]"]
  node_djangoapi["Django endpoints<br/>[views.py]"]
  node_serializers["Request serializers<br/>[serializers.py]"]
end

subgraph group_analysis["AI analysis"]
  node_scorelogic["Scorecard calculation"]
  node_openai["AI extraction and chat<br/>[openai_service.py]"]
end

subgraph group_data["Recruitment records"]
  node_records[("Recruitment records<br/>[models.py]")]
end

node_recruiter(("Recruiter"))
node_llmprovider(("OpenAI service"))

node_recruiter -->|"uses"| node_app
node_app -->|"renders"| node_header
node_app -->|"routes to"| node_home
node_app -->|"routes to"| node_scorecardpage
node_app -->|"routes to"| node_chatpage
node_home -->|"renders"| node_upload
node_home -->|"renders"| node_scorecardlist
node_home -->|"calls"| node_clientapi
node_scorecardlist -->|"loads"| node_clientapi
node_scorecardpage -->|"loads"| node_clientapi
node_chatpage -->|"calls"| node_clientapi
node_clientapi -.->|"HTTP requests"| node_djangoapi
node_djangoapi -->|"uses"| node_serializers
node_djangoapi -->|"extracts transcript"| node_openai
node_djangoapi -->|"generates scorecards"| node_scorelogic
node_scorelogic -->|"reads and writes"| node_records
node_scorelogic -->|"extracts data"| node_openai
node_djangoapi -->|"creates records"| node_records
node_openai -->|"requests completions"| node_llmprovider

click node_app "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/App.tsx"
click node_home "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/pages/HomePage.tsx"
click node_upload "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/components/FileUpload.tsx"
click node_scorecardlist "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/components/ScorecardList.tsx"
click node_scorecardpage "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/pages/ScorecardPage.tsx"
click node_chatpage "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/pages/ChatPage.tsx"
click node_header "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/components/Header.tsx"
click node_clientapi "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/services/api.ts"
click node_djangoapi "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/views.py"
click node_serializers "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/serializers.py"
click node_scorelogic "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/services/scorecard_service.py"
click node_openai "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/services/openai_service.py"
click node_records "https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/models.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_home,node_upload,node_scorecardlist,node_scorecardpage,node_chatpage,node_header toneBlue
class node_clientapi,node_djangoapi,node_serializers toneAmber
class node_scorelogic,node_openai toneMint
class node_records toneRose
class node_recruiter,node_llmprovider toneIndigo
```

## Components

### Recruiter interface

- [App routing](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Workflow home](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/pages/HomePage.tsx): `frontend/src/pages/HomePage.tsx`
- [File upload](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/components/FileUpload.tsx): `frontend/src/components/FileUpload.tsx`
- [Scorecard list](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/components/ScorecardList.tsx): `frontend/src/components/ScorecardList.tsx`
- [Scorecard view](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/pages/ScorecardPage.tsx): `frontend/src/pages/ScorecardPage.tsx`
- [Candidate chat](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/pages/ChatPage.tsx): `frontend/src/pages/ChatPage.tsx`
- [Header](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/components/Header.tsx): `frontend/src/components/Header.tsx`

### Application API

- [API client](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/frontend/src/services/api.ts): `frontend/src/services/api.ts`
- [Django endpoints](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/views.py): `backend/recruitment/views.py`
- [Request serializers](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/serializers.py): `backend/recruitment/serializers.py`

### AI analysis

- [Scorecard calculation](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/services/scorecard_service.py): `backend/recruitment/services/scorecard_service.py`
- [AI extraction and chat](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/services/openai_service.py): `backend/recruitment/services/openai_service.py`

### Recruitment records

- [Recruitment records](https://github.com/manish-joshi1/ai-recruitment-assistant/blob/main/backend/recruitment/models.py): `backend/recruitment/models.py`

### Other components

- **Recruiter**
- **OpenAI service**

## Connections

- Recruiter → App routing: uses
- App routing → Header: renders (evidence: `frontend/src/App.tsx`)
- App routing → Workflow home: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Scorecard view: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Candidate chat: routes to (evidence: `frontend/src/App.tsx`)
- Workflow home → File upload: renders (evidence: `frontend/src/pages/HomePage.tsx`)
- Workflow home → Scorecard list: renders (evidence: `frontend/src/pages/HomePage.tsx`)
- Workflow home → API client: calls (evidence: `frontend/src/pages/HomePage.tsx`)
- Scorecard list → API client: loads (evidence: `frontend/src/components/ScorecardList.tsx`)
- Scorecard view → API client: loads (evidence: `frontend/src/pages/ScorecardPage.tsx`)
- Candidate chat → API client: calls (evidence: `frontend/src/pages/ChatPage.tsx`)
- API client → Django endpoints: HTTP requests
- Django endpoints → Request serializers: uses (evidence: `backend/recruitment/views.py`)
- Django endpoints → AI extraction and chat: extracts transcript (evidence: `backend/recruitment/views.py`)
- Django endpoints → Scorecard calculation: generates scorecards (evidence: `backend/recruitment/views.py`)
- Scorecard calculation → Recruitment records: reads and writes (evidence: `backend/recruitment/services/scorecard_service.py`)
- Scorecard calculation → AI extraction and chat: extracts data (evidence: `backend/recruitment/services/scorecard_service.py`)
- Django endpoints → Recruitment records: creates records (evidence: `backend/recruitment/views.py`)
- AI extraction and chat → OpenAI service: requests completions (evidence: `backend/recruitment/services/openai_service.py`)
