# piruthvin/email_based_candidate_screening architecture

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

- Interactive diagram: https://gitdiagram.com/piruthvin/email_based_candidate_screening
- Repository: https://github.com/piruthvin/email_based_candidate_screening

## Overview

This is an email-driven candidate-screening backend. The main workflow syncs or receives candidate mail, parses and deduplicates candidate data, stores resumes and applications, queues scoring against active job profiles, and exposes search, ranking, dossiers, and reports to recruiter tools. The graph combines sampled call sites and SOURCE INDEX references with README-documented capabilities; several tool endpoints and ingestion details are not fully sampled, so their internal relationships are shown only where documented.

Main entry points: [`backend/app/workers/ingest_worker.py`](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/workers/ingest_worker.py) (Ingestion Worker), [`backend/app/services/scoring_pipeline.py`](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/scoring_pipeline.py) (Scoring Pipeline), [`backend/app/main.py`](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/main.py) (FastAPI Application), [`backend/app/services/tool_service.py`](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/tool_service.py) (Recruiter Operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingest["Mail Ingestion"]
  node_graph_sync["Mailbox Sync"]
  node_ingest_worker["Ingestion Worker<br/>[ingest_worker.py]"]
  node_nvite_parser["Mail Parser<br/>[nvite_parser.py]"]
  node_resume_service["Resume Processing<br/>[resume_service.py]"]
  node_dedupe["Candidate Deduplication<br/>[dedupe_service.py]"]
end

subgraph group_scoring["Candidate Scoring"]
  node_scoring_jobs["Scoring Jobs<br/>[models.py]"]
  node_scoring_worker["Scoring Worker<br/>[scoring_worker.py]"]
  node_scoring_pipeline["Scoring Pipeline"]
  node_details_scorer["Details Scorer<br/>[details_scorer.py]"]
  node_agent_client["Scoring Agent Client"]
  node_grounding["Evidence Grounding"]
end

subgraph group_recruiter["Recruiter Tools"]
  node_tool_api["Tool API<br/>[tools.py]"]
  node_tool_schemas["Tool Schemas<br/>[tools.py]"]
  node_tool_service["Recruiter Operations<br/>[tool_service.py]"]
  node_report_service["Excel Reports<br/>[report_service.py]"]
  node_report_download["Report Download<br/>[reports.py]"]
end

subgraph group_platform["Backend Platform"]
  node_database[("PostgreSQL")]
  node_db_access["Database Access<br/>[database.py]"]
  node_models["Data Models<br/>[models.py]"]
  node_config["Application Config<br/>[config.py]"]
  node_app_entry["FastAPI Application<br/>[main.py]"]
end

node_candidate_email(("Candidate Email"))
node_m365["Microsoft 365"]
node_nvite_mail["nVitae Mail"]
node_scoring_agent["iGentic Scoring Agent"]
node_recruiter(("Recruiter"))

node_m365 -->|"provides mailbox data"| node_graph_sync
node_graph_sync -->|"queues mail"| node_ingest_worker
node_candidate_email -->|"arrives as"| node_nvite_mail
node_nvite_mail -->|"enters processing"| node_ingest_worker
node_ingest_worker -->|"parses mail"| node_nvite_parser
node_ingest_worker -->|"checks duplicates"| node_dedupe
node_ingest_worker -->|"processes resume"| node_resume_service
node_ingest_worker -->|"queues scoring"| node_scoring_jobs
node_scoring_jobs -->|"polled by"| node_scoring_worker
node_scoring_worker -->|"runs scoring"| node_scoring_pipeline
node_scoring_pipeline -->|"scores candidate details"| node_details_scorer
node_scoring_pipeline -->|"requests resume evaluation"| node_agent_client
node_agent_client -->|"invokes"| node_scoring_agent
node_scoring_pipeline -->|"validates evidence"| node_grounding
node_recruiter -->|"uses tools"| node_tool_api
node_tool_api -->|"dispatches operations"| node_tool_service
node_tool_api -->|"validates payloads"| node_tool_schemas
node_tool_service -->|"starts mailbox sync"| node_graph_sync
node_tool_service -->|"generates reports"| node_report_service
node_tool_service -->|"queries screening data"| node_models
node_report_service -->|"provides download"| node_report_download
node_app_entry -->|"registers routes"| node_tool_api
node_app_entry -->|"registers routes"| node_report_download
node_app_entry -->|"starts worker"| node_ingest_worker
node_app_entry -->|"starts worker"| node_scoring_worker
node_db_access -->|"loads database settings"| node_config
node_scoring_pipeline -->|"reads and writes scores"| node_models
node_ingest_worker -->|"stores candidate records"| node_models
node_graph_sync -->|"stores synced mail"| node_models
node_db_access -->|"connects to"| node_database

click node_graph_sync "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/graph_sync_service.py"
click node_ingest_worker "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/workers/ingest_worker.py"
click node_nvite_parser "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/nvite_parser.py"
click node_resume_service "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/resume_service.py"
click node_dedupe "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/dedupe_service.py"
click node_scoring_jobs "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/db/models.py"
click node_scoring_worker "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/workers/scoring_worker.py"
click node_scoring_pipeline "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/scoring_pipeline.py"
click node_details_scorer "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/details_scorer.py"
click node_agent_client "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/scoring_agent_client.py"
click node_grounding "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/evidence_grounding.py"
click node_tool_api "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/api/v1/tools.py"
click node_tool_schemas "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/schemas/tools.py"
click node_tool_service "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/tool_service.py"
click node_report_service "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/report_service.py"
click node_report_download "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/api/v1/reports.py"
click node_db_access "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/core/database.py"
click node_models "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/db/models.py"
click node_config "https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/core/config.py"
click node_app_entry "https://github.com/piruthvin/email_based_candidate_screening/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_graph_sync,node_ingest_worker,node_nvite_parser,node_resume_service,node_dedupe toneBlue
class node_scoring_jobs,node_scoring_worker,node_scoring_pipeline,node_details_scorer,node_agent_client,node_grounding toneAmber
class node_tool_api,node_tool_schemas,node_tool_service,node_report_service,node_report_download toneMint
class node_database,node_db_access,node_models,node_config,node_app_entry toneRose
class node_candidate_email,node_m365,node_nvite_mail,node_scoring_agent,node_recruiter toneIndigo
```

## Components

### Mail Ingestion

- [Mailbox Sync](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/graph_sync_service.py): `backend/app/services/graph_sync_service.py`
- [Ingestion Worker](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/workers/ingest_worker.py): `backend/app/workers/ingest_worker.py`
- [Mail Parser](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/nvite_parser.py): `backend/app/services/nvite_parser.py`
- [Resume Processing](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/resume_service.py): `backend/app/services/resume_service.py`
- [Candidate Deduplication](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/dedupe_service.py): `backend/app/services/dedupe_service.py`

### Candidate Scoring

- [Scoring Jobs](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Scoring Worker](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/workers/scoring_worker.py): `backend/app/workers/scoring_worker.py`
- [Scoring Pipeline](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/scoring_pipeline.py): `backend/app/services/scoring_pipeline.py`
- [Details Scorer](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/details_scorer.py): `backend/app/services/details_scorer.py`
- [Scoring Agent Client](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/scoring_agent_client.py): `backend/app/services/scoring_agent_client.py`
- [Evidence Grounding](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/evidence_grounding.py): `backend/app/services/evidence_grounding.py`

### Recruiter Tools

- [Tool API](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/api/v1/tools.py): `backend/app/api/v1/tools.py`
- [Tool Schemas](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/schemas/tools.py): `backend/app/schemas/tools.py`
- [Recruiter Operations](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/tool_service.py): `backend/app/services/tool_service.py`
- [Excel Reports](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/services/report_service.py): `backend/app/services/report_service.py`
- [Report Download](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/api/v1/reports.py): `backend/app/api/v1/reports.py`

### Backend Platform

- **PostgreSQL**
- [Database Access](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/core/database.py): `backend/app/core/database.py`
- [Data Models](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/db/models.py): `backend/app/db/models.py`
- [Application Config](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/core/config.py): `backend/app/core/config.py`
- [FastAPI Application](https://github.com/piruthvin/email_based_candidate_screening/blob/main/backend/app/main.py): `backend/app/main.py`

### Other components

- **Candidate Email**
- **Microsoft 365**
- **nVitae Mail**
- **iGentic Scoring Agent**
- **Recruiter**

## Connections

- Microsoft 365 → Mailbox Sync: provides mailbox data (evidence: `README.md`)
- Mailbox Sync → Ingestion Worker: queues mail (evidence: `README.md`)
- Candidate Email → nVitae Mail: arrives as (evidence: `README.md`)
- nVitae Mail → Ingestion Worker: enters processing (evidence: `README.md`)
- Ingestion Worker → Mail Parser: parses mail (evidence: `backend/app/workers/ingest_worker.py`)
- Ingestion Worker → Candidate Deduplication: checks duplicates (evidence: `backend/app/workers/ingest_worker.py`)
- Ingestion Worker → Resume Processing: processes resume (evidence: `README.md`)
- Ingestion Worker → Scoring Jobs: queues scoring (evidence: `README.md`)
- Scoring Jobs → Scoring Worker: polled by (evidence: `README.md`)
- Scoring Worker → Scoring Pipeline: runs scoring (evidence: `backend/app/workers/scoring_worker.py`)
- Scoring Pipeline → Details Scorer: scores candidate details (evidence: `backend/app/services/scoring_pipeline.py`)
- Scoring Pipeline → Scoring Agent Client: requests resume evaluation (evidence: `backend/app/services/scoring_pipeline.py`)
- Scoring Agent Client → iGentic Scoring Agent: invokes (evidence: `README.md`)
- Scoring Pipeline → Evidence Grounding: validates evidence (evidence: `backend/app/services/scoring_pipeline.py`)
- Recruiter → Tool API: uses tools (evidence: `README.md`)
- Tool API → Recruiter Operations: dispatches operations (evidence: `backend/app/api/v1/tools.py`)
- Tool API → Tool Schemas: validates payloads (evidence: `backend/app/api/v1/tools.py`)
- Recruiter Operations → Mailbox Sync: starts mailbox sync (evidence: `backend/app/services/tool_service.py`)
- Recruiter Operations → Excel Reports: generates reports (evidence: `backend/app/services/tool_service.py`)
- Recruiter Operations → Data Models: queries screening data (evidence: `backend/app/services/tool_service.py`)
- Excel Reports → Report Download: provides download (evidence: `README.md`)
- FastAPI Application → Tool API: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → Report Download: registers routes (evidence: `backend/app/main.py`)
- FastAPI Application → Ingestion Worker: starts worker (evidence: `backend/app/main.py`)
- FastAPI Application → Scoring Worker: starts worker (evidence: `backend/app/main.py`)
- Database Access → Application Config: loads database settings (evidence: `backend/app/core/database.py`)
- Scoring Pipeline → Data Models: reads and writes scores (evidence: `backend/app/services/scoring_pipeline.py`)
- Ingestion Worker → Data Models: stores candidate records (evidence: `backend/app/workers/ingest_worker.py`)
- Mailbox Sync → Data Models: stores synced mail (evidence: `backend/app/services/graph_sync_service.py`)
- Database Access → PostgreSQL: connects to (evidence: `README.md`)
