# ashishch01/talentdesk architecture

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

- Interactive diagram: https://gitdiagram.com/ashishch01/talentdesk
- Repository: https://github.com/ashishch01/talentdesk

## Overview

TalentDesk AI is an educational recruiter-copilot demo: candidates submit PDF résumés, recruiters ask the copilot to search and screen candidates, check compensation, update records, or send simulated email, and the UI exposes resulting activity and state. The main path is application intake → PDF text extraction → candidate storage → agent tool calls → database changes or simulated inbox entries. The README documents the attack scenario and major views. Sampled source confirms the API, UI, extraction, and agent paths; tool internals and data models were not sampled, so their detailed wiring is limited to documented behavior.

Main entry points: [`backend/app/main.py`](https://github.com/ashishch01/talentdesk/blob/main/backend/app/main.py) (FastAPI endpoints), [`frontend/src/api.js`](https://github.com/ashishch01/talentdesk/blob/main/frontend/src/api.js) (API client), [`backend/app/database.py`](https://github.com/ashishch01/talentdesk/blob/main/backend/app/database.py) (Database sessions), [`frontend/src/pages/RecruiterDashboard.jsx`](https://github.com/ashishch01/talentdesk/blob/main/frontend/src/pages/RecruiterDashboard.jsx) (Recruiter dashboard)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_application["Application intake"]
  node_apply_ui["Apply page<br/>[ApplyPage.jsx]"]
  node_api_client["API client<br/>[api.js]"]
  node_api["FastAPI endpoints<br/>[main.py]"]
  node_pdf_extract["PDF text extraction<br/>[services.py]"]
  node_supabase_storage[("Résumé object storage")]
end

subgraph group_copilot["Recruiter copilot"]
  node_dashboard["Recruiter dashboard"]
  node_agent["Agent orchestration<br/>[agent.py]"]
  node_tool_registry["Recruiter tools<br/>[tools.py]"]
  node_gemini["Gemini"]
  node_groq["Groq fallback"]
end

subgraph group_state["Recruiting data"]
  node_db_session["Database sessions<br/>[database.py]"]
  node_models["Recruiting models<br/>[models.py]"]
  node_database[("Supabase Postgres")]
end

subgraph group_observability["Demo observability"]
  node_db_viewer["Database viewer<br/>[DatabaseViewer.jsx]"]
  node_attacker_inbox["Simulated inbox view<br/>[AttackerInbox.jsx]"]
  node_activity_stream["Activity stream<br/>[main.py]"]
end

node_candidate(("Candidate"))
node_recruiter(("Recruiter"))
node_attacker(("Attacker"))

node_candidate -->|"submits résumé"| node_apply_ui
node_apply_ui -->|"posts application"| node_api_client
node_api_client -->|"sends request"| node_api
node_api -->|"extracts text"| node_pdf_extract
node_api -->|"stores candidate"| node_db_session
node_api -.->|"uploads PDF"| node_supabase_storage
node_recruiter -->|"asks copilot"| node_dashboard
node_dashboard -->|"posts chat"| node_api_client
node_api_client -->|"sends chat"| node_api
node_api -->|"processes request"| node_agent
node_agent -->|"tries model"| node_gemini
node_agent -.->|"falls back"| node_groq
node_agent -->|"dispatches tools"| node_tool_registry
node_tool_registry -->|"reads and updates"| node_db_session
node_db_session -->|"queries and commits"| node_database
node_models -->|"defines mappings"| node_db_session
node_dashboard -->|"opens SSE"| node_activity_stream
node_api -->|"serves events"| node_activity_stream
node_dashboard -->|"loads candidates"| node_api_client
node_db_viewer -->|"loads records"| node_api_client
node_attacker_inbox -->|"loads inbox"| node_api_client
node_api_client -->|"requests views"| node_api
node_api -->|"reads views"| node_db_session
node_attacker -->|"observes leaks"| node_attacker_inbox

click node_apply_ui "https://github.com/ashishch01/talentdesk/blob/main/frontend/src/pages/ApplyPage.jsx"
click node_api_client "https://github.com/ashishch01/talentdesk/blob/main/frontend/src/api.js"
click node_api "https://github.com/ashishch01/talentdesk/blob/main/backend/app/main.py"
click node_pdf_extract "https://github.com/ashishch01/talentdesk/blob/main/backend/app/services.py"
click node_dashboard "https://github.com/ashishch01/talentdesk/blob/main/frontend/src/pages/RecruiterDashboard.jsx"
click node_agent "https://github.com/ashishch01/talentdesk/blob/main/backend/app/agent.py"
click node_tool_registry "https://github.com/ashishch01/talentdesk/blob/main/backend/app/tools.py"
click node_db_session "https://github.com/ashishch01/talentdesk/blob/main/backend/app/database.py"
click node_models "https://github.com/ashishch01/talentdesk/blob/main/backend/app/models.py"
click node_db_viewer "https://github.com/ashishch01/talentdesk/blob/main/frontend/src/pages/DatabaseViewer.jsx"
click node_attacker_inbox "https://github.com/ashishch01/talentdesk/blob/main/frontend/src/pages/AttackerInbox.jsx"
click node_activity_stream "https://github.com/ashishch01/talentdesk/blob/main/backend/app/main.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_apply_ui,node_api_client,node_api,node_pdf_extract,node_supabase_storage toneBlue
class node_dashboard,node_agent,node_tool_registry,node_gemini,node_groq toneAmber
class node_db_session,node_models,node_database toneMint
class node_db_viewer,node_attacker_inbox,node_activity_stream toneRose
class node_candidate,node_recruiter,node_attacker toneIndigo
```

## Components

### Application intake

- [Apply page](https://github.com/ashishch01/talentdesk/blob/main/frontend/src/pages/ApplyPage.jsx): `frontend/src/pages/ApplyPage.jsx`
- [API client](https://github.com/ashishch01/talentdesk/blob/main/frontend/src/api.js): `frontend/src/api.js`
- [FastAPI endpoints](https://github.com/ashishch01/talentdesk/blob/main/backend/app/main.py): `backend/app/main.py`
- [PDF text extraction](https://github.com/ashishch01/talentdesk/blob/main/backend/app/services.py): `backend/app/services.py`
- **Résumé object storage**

### Recruiter copilot

- [Recruiter dashboard](https://github.com/ashishch01/talentdesk/blob/main/frontend/src/pages/RecruiterDashboard.jsx): `frontend/src/pages/RecruiterDashboard.jsx`
- [Agent orchestration](https://github.com/ashishch01/talentdesk/blob/main/backend/app/agent.py): `backend/app/agent.py`
- [Recruiter tools](https://github.com/ashishch01/talentdesk/blob/main/backend/app/tools.py): `backend/app/tools.py`
- **Gemini**
- **Groq fallback**

### Recruiting data

- [Database sessions](https://github.com/ashishch01/talentdesk/blob/main/backend/app/database.py): `backend/app/database.py`
- [Recruiting models](https://github.com/ashishch01/talentdesk/blob/main/backend/app/models.py): `backend/app/models.py`
- **Supabase Postgres**

### Demo observability

- [Database viewer](https://github.com/ashishch01/talentdesk/blob/main/frontend/src/pages/DatabaseViewer.jsx): `frontend/src/pages/DatabaseViewer.jsx`
- [Simulated inbox view](https://github.com/ashishch01/talentdesk/blob/main/frontend/src/pages/AttackerInbox.jsx): `frontend/src/pages/AttackerInbox.jsx`
- [Activity stream](https://github.com/ashishch01/talentdesk/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Candidate**
- **Recruiter**
- **Attacker**

## Connections

- Candidate → Apply page: submits résumé
- Apply page → API client: posts application
- API client → FastAPI endpoints: sends request
- FastAPI endpoints → PDF text extraction: extracts text
- FastAPI endpoints → Database sessions: stores candidate
- FastAPI endpoints → Résumé object storage: uploads PDF
- Recruiter → Recruiter dashboard: asks copilot
- Recruiter dashboard → API client: posts chat
- API client → FastAPI endpoints: sends chat
- FastAPI endpoints → Agent orchestration: processes request
- Agent orchestration → Gemini: tries model
- Agent orchestration → Groq fallback: falls back
- Agent orchestration → Recruiter tools: dispatches tools
- Recruiter tools → Database sessions: reads and updates
- Database sessions → Supabase Postgres: queries and commits
- Recruiting models → Database sessions: defines mappings
- Recruiter dashboard → Activity stream: opens SSE
- FastAPI endpoints → Activity stream: serves events
- Recruiter dashboard → API client: loads candidates
- Database viewer → API client: loads records
- Simulated inbox view → API client: loads inbox
- API client → FastAPI endpoints: requests views
- FastAPI endpoints → Database sessions: reads views
- Attacker → Simulated inbox view: observes leaks