# piruthvin/employee-referral-optimization-agent architecture

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

- Interactive diagram: https://gitdiagram.com/piruthvin/employee-referral-optimization-agent
- Repository: https://github.com/piruthvin/employee-referral-optimization-agent

## Overview

This is an employee-referral and recruitment operations platform: employees authenticate and submit candidate referrals, while recruiters review them, schedule interviews, and track outcomes. The frontend routes role-specific users and sends authenticated API requests to a FastAPI backend. Backend services handle resume parsing and job matching, persist recruitment records in Zoho Recruit, and integrate with Microsoft Graph for email and interview coordination; iGentic provides chat and AI capabilities. Analytics and job discovery are additional product branches. Some connections are documented in the README or source index rather than fully shown in excerpts.

Main entry points: [`backend/app/main.py`](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/main.py) (FastAPI application), [`backend/app/services/zoho_service.py`](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/zoho_service.py) (Zoho integration), [`frontend/src/api/client.ts`](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/api/client.ts) (API client), [`frontend/src/App.tsx`](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/App.tsx) (App routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web application"]
  node_app["App routing<br/>[App.tsx]"]
  node_login["Login page<br/>[LoginPage.tsx]"]
  node_employee_ui["Employee dashboard"]
  node_recruiter_ui["Recruiter dashboard"]
  node_approval_ui["Approval detail"]
  node_chat_ui["Chat page<br/>[ChatPage.tsx]"]
  node_auth_store["Auth state<br/>[authStore.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_api["API and identity"]
  node_fastapi["FastAPI application<br/>[main.py]"]
  node_auth_api["Authentication API<br/>[auth.py]"]
  node_security["JWT and OTP security<br/>[security.py]"]
  node_dependencies["Auth dependencies<br/>[dependencies.py]"]
end

subgraph group_referrals["Referral lifecycle"]
  node_referral_api["Referral API<br/>[referral.py]"]
  node_referral_service["Referral intake"]
  node_resume["Resume parsing"]
  node_python_parser["Python parser"]
  node_matching["Job matching"]
end

subgraph group_operations["Recruitment operations"]
  node_approval_api["Approval API<br/>[approvals.py]"]
  node_approval_service["Approval workflow"]
  node_interview_api["Interview API<br/>[interview.py]"]
  node_interview_service["Interview scheduling"]
  node_analytics_api["Analytics API<br/>[analytics.py]"]
  node_analytics_service["Funnel analytics"]
  node_jobs_api["Jobs API<br/>[jobs.py]"]
end

subgraph group_integrations["External services"]
  node_zoho[("Zoho Recruit")]
  node_zoho_service["Zoho integration<br/>[zoho_service.py]"]
  node_zoho_users["Zoho user directory"]
  node_zoho_auth["Zoho OAuth<br/>[zoho_auth.py]"]
  node_graph["Microsoft Graph"]
  node_email["Email service<br/>[email_service.py]"]
  node_igentic["iGentic agents"]
  node_igentic_client["iGentic client<br/>[igentic_client.py]"]
end

node_employee(("Employee"))
node_recruiter(("Recruiter"))

node_employee -->|"signs in"| node_login
node_login -->|"sets session"| node_auth_store
node_app -->|"routes to"| node_login
node_app -->|"routes to"| node_employee_ui
node_app -->|"routes to"| node_recruiter_ui
node_app -->|"routes to"| node_approval_ui
node_app -->|"routes to"| node_chat_ui
node_employee_ui -->|"requests data"| node_api_client
node_recruiter_ui -->|"requests data"| node_api_client
node_approval_ui -->|"requests actions"| node_api_client
node_chat_ui -.->|"requests chat"| node_api_client
node_auth_store -->|"provides token"| node_api_client
node_api_client -->|"sends HTTPS requests"| node_fastapi
node_fastapi -->|"mounts routes"| node_auth_api
node_fastapi -->|"mounts routes"| node_referral_api
node_fastapi -->|"mounts routes"| node_approval_api
node_fastapi -->|"mounts routes"| node_interview_api
node_fastapi -->|"mounts routes"| node_analytics_api
node_fastapi -->|"mounts routes"| node_jobs_api
node_auth_api -->|"uses tokens"| node_security
node_auth_api -->|"verifies user"| node_zoho_users
node_auth_api -->|"sends OTP"| node_email
node_dependencies -->|"validates JWT"| node_security
node_dependencies -->|"looks up user"| node_zoho_users
node_referral_api -->|"handles intake"| node_referral_service
node_referral_api -->|"reads and writes"| node_zoho_service
node_referral_service -.->|"parses resume"| node_resume
node_referral_service -.->|"scores candidate"| node_matching
node_resume -->|"parses with agent"| node_igentic_client
node_resume -->|"uses fallback"| node_python_parser
node_matching -->|"requests agent match"| node_igentic_client
node_matching -->|"uses profile parser"| node_python_parser
node_approval_api -->|"handles review"| node_approval_service
node_approval_service -->|"updates candidate"| node_zoho_service
node_approval_service -->|"sends notices"| node_email
node_interview_api -->|"schedules interview"| node_interview_service
node_interview_service -->|"creates Teams meeting"| node_graph
node_interview_service -.->|"updates candidate"| node_zoho_service
node_analytics_api -->|"calculates metrics"| node_analytics_service
node_analytics_service -.->|"reads candidates"| node_zoho_service
node_jobs_api -.->|"matches candidates"| node_matching
node_zoho_service -->|"gets access token"| node_zoho_auth
node_zoho_users -->|"gets access token"| node_zoho_auth
node_zoho_service -->|"reads and writes"| node_zoho
node_zoho_users -->|"queries users"| node_zoho
node_email -->|"sends email"| node_graph
node_igentic_client -->|"calls agent executor"| node_igentic
node_recruiter -->|"reviews referrals"| node_recruiter_ui

click node_app "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/App.tsx"
click node_login "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/LoginPage.tsx"
click node_employee_ui "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/employee/EmployeeDashboard.tsx"
click node_recruiter_ui "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/recruiter/RecruiterDashboard.tsx"
click node_approval_ui "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/recruiter/ApprovalDetailPage.tsx"
click node_chat_ui "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/chat/ChatPage.tsx"
click node_auth_store "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/store/authStore.ts"
click node_api_client "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/api/client.ts"
click node_fastapi "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/main.py"
click node_auth_api "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/auth.py"
click node_security "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/core/security.py"
click node_dependencies "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/core/dependencies.py"
click node_referral_api "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/referral.py"
click node_referral_service "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/referral_service.py"
click node_resume "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/resume_parser_service.py"
click node_python_parser "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/resume_parser_python.py"
click node_matching "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/job_match_service.py"
click node_approval_api "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/approvals.py"
click node_approval_service "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/approval_service.py"
click node_interview_api "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/interview.py"
click node_interview_service "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/interview_service.py"
click node_analytics_api "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/analytics.py"
click node_analytics_service "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/analytics_service.py"
click node_jobs_api "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/jobs.py"
click node_zoho_service "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/zoho_service.py"
click node_zoho_users "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/zoho_users_service.py"
click node_zoho_auth "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/infrastructure/zoho_auth.py"
click node_email "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/email_service.py"
click node_igentic_client "https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/igentic_client.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_login,node_employee_ui,node_recruiter_ui,node_approval_ui,node_chat_ui,node_auth_store,node_api_client toneBlue
class node_fastapi,node_auth_api,node_security,node_dependencies toneAmber
class node_referral_api,node_referral_service,node_resume,node_python_parser,node_matching toneMint
class node_approval_api,node_approval_service,node_interview_api,node_interview_service,node_analytics_api,node_analytics_service,node_jobs_api toneRose
class node_zoho,node_zoho_service,node_zoho_users,node_zoho_auth,node_graph,node_email,node_igentic,node_igentic_client,node_employee,node_recruiter toneIndigo
```

## Components

### Web application

- [App routing](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Login page](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/LoginPage.tsx): `frontend/src/pages/LoginPage.tsx`
- [Employee dashboard](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/employee/EmployeeDashboard.tsx): `frontend/src/pages/employee/EmployeeDashboard.tsx`
- [Recruiter dashboard](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/recruiter/RecruiterDashboard.tsx): `frontend/src/pages/recruiter/RecruiterDashboard.tsx`
- [Approval detail](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/recruiter/ApprovalDetailPage.tsx): `frontend/src/pages/recruiter/ApprovalDetailPage.tsx`
- [Chat page](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/pages/chat/ChatPage.tsx): `frontend/src/pages/chat/ChatPage.tsx`
- [Auth state](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/store/authStore.ts): `frontend/src/store/authStore.ts`
- [API client](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`

### API and identity

- [FastAPI application](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/main.py): `backend/app/main.py`
- [Authentication API](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/auth.py): `backend/app/api/v1/auth.py`
- [JWT and OTP security](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/core/security.py): `backend/app/core/security.py`
- [Auth dependencies](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/core/dependencies.py): `backend/app/core/dependencies.py`

### Referral lifecycle

- [Referral API](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/referral.py): `backend/app/api/v1/referral.py`
- [Referral intake](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/referral_service.py): `backend/app/services/referral_service.py`
- [Resume parsing](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/resume_parser_service.py): `backend/app/services/resume_parser_service.py`
- [Python parser](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/resume_parser_python.py): `backend/app/services/resume_parser_python.py`
- [Job matching](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/job_match_service.py): `backend/app/services/job_match_service.py`

### Recruitment operations

- [Approval API](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/approvals.py): `backend/app/api/v1/approvals.py`
- [Approval workflow](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/approval_service.py): `backend/app/services/approval_service.py`
- [Interview API](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/interview.py): `backend/app/api/v1/interview.py`
- [Interview scheduling](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/interview_service.py): `backend/app/services/interview_service.py`
- [Analytics API](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/analytics.py): `backend/app/api/v1/analytics.py`
- [Funnel analytics](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/analytics_service.py): `backend/app/services/analytics_service.py`
- [Jobs API](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/api/v1/jobs.py): `backend/app/api/v1/jobs.py`

### External services

- **Zoho Recruit**
- [Zoho integration](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/zoho_service.py): `backend/app/services/zoho_service.py`
- [Zoho user directory](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/zoho_users_service.py): `backend/app/services/zoho_users_service.py`
- [Zoho OAuth](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/infrastructure/zoho_auth.py): `backend/app/infrastructure/zoho_auth.py`
- **Microsoft Graph**
- [Email service](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/email_service.py): `backend/app/services/email_service.py`
- **iGentic agents**
- [iGentic client](https://github.com/piruthvin/employee-referral-optimization-agent/blob/main/backend/app/services/igentic_client.py): `backend/app/services/igentic_client.py`

### Other components

- **Employee**
- **Recruiter**

## Connections

- Employee → Login page: signs in (evidence: `README.md`)
- Login page → Auth state: sets session
- App routing → Login page: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Employee dashboard: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Recruiter dashboard: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Approval detail: routes to (evidence: `frontend/src/App.tsx`)
- App routing → Chat page: routes to (evidence: `frontend/src/App.tsx`)
- Employee dashboard → API client: requests data (evidence: `frontend/src/pages/employee/EmployeeDashboard.tsx`)
- Recruiter dashboard → API client: requests data (evidence: `frontend/src/pages/recruiter/RecruiterDashboard.tsx`)
- Approval detail → API client: requests actions (evidence: `frontend/src/pages/recruiter/ApprovalDetailPage.tsx`)
- Chat page → API client: requests chat
- Auth state → API client: provides token (evidence: `frontend/src/api/client.ts`)
- API client → FastAPI application: sends HTTPS requests (evidence: `README.md`)
- FastAPI application → Authentication API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Referral API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Approval API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Interview API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Analytics API: mounts routes (evidence: `backend/app/main.py`)
- FastAPI application → Jobs API: mounts routes (evidence: `backend/app/main.py`)
- Authentication API → JWT and OTP security: uses tokens (evidence: `backend/app/api/v1/auth.py`)
- Authentication API → Zoho user directory: verifies user (evidence: `backend/app/api/v1/auth.py`)
- Authentication API → Email service: sends OTP (evidence: `backend/app/api/v1/auth.py`)
- Auth dependencies → JWT and OTP security: validates JWT (evidence: `backend/app/core/dependencies.py`)
- Auth dependencies → Zoho user directory: looks up user (evidence: `backend/app/core/dependencies.py`)
- Referral API → Referral intake: handles intake (evidence: `backend/app/api/v1/referral.py`)
- Referral API → Zoho integration: reads and writes (evidence: `backend/app/api/v1/referral.py`)
- Referral intake → Resume parsing: parses resume
- Referral intake → Job matching: scores candidate
- Resume parsing → iGentic client: parses with agent (evidence: `backend/app/services/resume_parser_service.py`)
- Resume parsing → Python parser: uses fallback (evidence: `backend/app/services/resume_parser_service.py`)
- Job matching → iGentic client: requests agent match (evidence: `backend/app/services/job_match_service.py`)
- Job matching → Python parser: uses profile parser (evidence: `backend/app/services/job_match_service.py`)
- Approval API → Approval workflow: handles review (evidence: `backend/app/api/v1/approvals.py`)
- Approval workflow → Zoho integration: updates candidate (evidence: `backend/app/services/approval_service.py`)
- Approval workflow → Email service: sends notices (evidence: `backend/app/services/approval_service.py`)
- Interview API → Interview scheduling: schedules interview (evidence: `backend/app/api/v1/interview.py`)
- Interview scheduling → Microsoft Graph: creates Teams meeting (evidence: `README.md`)
- Interview scheduling → Zoho integration: updates candidate
- Analytics API → Funnel analytics: calculates metrics (evidence: `backend/app/api/v1/analytics.py`)
- Funnel analytics → Zoho integration: reads candidates
- Jobs API → Job matching: matches candidates
- Zoho integration → Zoho OAuth: gets access token (evidence: `backend/app/services/zoho_service.py`)
- Zoho user directory → Zoho OAuth: gets access token (evidence: `backend/app/services/zoho_users_service.py`)
- Zoho integration → Zoho Recruit: reads and writes (evidence: `README.md`)
- Zoho user directory → Zoho Recruit: queries users (evidence: `README.md`)
- Email service → Microsoft Graph: sends email (evidence: `README.md`)
- iGentic client → iGentic agents: calls agent executor (evidence: `backend/app/services/igentic_client.py`)
- Recruiter → Recruiter dashboard: reviews referrals (evidence: `README.md`)
