# aliashrafabbasi/hireflow-ai-backend architecture

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

- Interactive diagram: https://gitdiagram.com/aliashrafabbasi/hireflow-ai-backend
- Repository: https://github.com/aliashrafabbasi/hireflow-ai-backend

## Overview

HireFlow is a FastAPI hiring backend for staff screening and a user career portal. Staff or career users enter through the versioned API; resume handling extracts candidate details and skills, while job analysis and matching produce scored, qualified-job results stored for later retrieval. Admins manage accounts and match thresholds. The README also documents an n8n/Gmail-to-visible-browser RPA workflow with Slack alerts. Core API and service relationships are supported by the excerpts and source index; some automation and career-service internals are documented but unsampled.

Main entry points: [`app/api/v1/endpoints`](https://github.com/aliashrafabbasi/hireflow-ai-backend/tree/main/app/api/v1/endpoints) (API endpoints), [`app/api/v1/api.py`](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/api/v1/api.py) (API router), [`app/services/resume.py`](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/resume.py) (Resume management), [`app/services/matching.py`](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/matching.py) (Match engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["API and access"]
  node_app["Application startup<br/>[main.py]"]
  node_router["API router<br/>[api.py]"]
  node_endpoints["API endpoints"]
end

subgraph group_screening["Resume screening"]
  node_resume_service["Resume management<br/>[resume.py]"]
  node_resume_parser["Resume parsing<br/>[resume_parser.py]"]
  node_resume_analyzer["Resume analysis<br/>[resume_analyzer.py]"]
  node_llm["LLM client<br/>[llm.py]"]
end

subgraph group_matching["Jobs and matching"]
  node_job_service["Job management<br/>[job.py]"]
  node_matching["Match engine<br/>[matching.py]"]
  node_match_analyzer["Match analysis<br/>[match_analyzer.py]"]
  node_match_repo["Match results repository<br/>[match_result.py]"]
end

subgraph group_data["Persistence and identity"]
  node_auth["JWT and role access<br/>[auth.py]"]
  node_auth_service["Account service<br/>[auth.py]"]
  node_user_repo["User repository<br/>[user.py]"]
  node_db_session["Database sessions<br/>[session.py]"]
  node_user_model[("User records<br/>[user.py]")]
  node_resume_model[("Resume records<br/>[resume.py]")]
  node_match_model[("Match records<br/>[match_result.py]")]
end

subgraph group_automation["Career and automation"]
  node_career["Career portal services<br/>[career.py]"]
  node_rpa_endpoint["RPA endpoints<br/>[rpa.py]"]
  node_rpa_browser["Visible browser RPA<br/>[rpa_browser.py]"]
end

node_actors(("Staff and candidates"))
node_n8n["n8n workflow"]
node_gmail["Gmail inbox"]
node_slack["Slack"]
node_frontend["HireFlow frontend"]
node_groq["Groq LLM"]
node_postgres[("PostgreSQL")]

node_actors -->|"use API"| node_router
node_n8n -->|"invoke automation"| node_router
node_app -->|"mounts routes"| node_router
node_router -->|"registers routes"| node_endpoints
node_endpoints -->|"protects requests"| node_auth
node_endpoints -->|"handles accounts"| node_auth_service
node_auth -->|"loads user"| node_user_repo
node_auth_service -->|"manages accounts"| node_user_repo
node_user_repo -->|"queries users"| node_user_model
node_endpoints -->|"handles resumes"| node_resume_service
node_endpoints -->|"requests scores"| node_matching
node_endpoints -->|"career resume actions"| node_resume_service
node_endpoints -->|"career portal requests"| node_career
node_resume_service -.->|"parses uploads"| node_resume_parser
node_resume_parser -->|"analyzes text"| node_resume_analyzer
node_resume_analyzer -->|"requests analysis"| node_llm
node_llm -->|"sends prompts"| node_groq
node_endpoints -->|"manages jobs"| node_job_service
node_job_service -.->|"analyzes descriptions"| node_groq
node_matching -->|"delegates analysis"| node_match_analyzer
node_matching -->|"reads and saves"| node_match_repo
node_match_repo -->|"persists results"| node_match_model
node_resume_service -.->|"stores resumes"| node_resume_model
node_db_session -->|"opens sessions"| node_postgres
node_rpa_endpoint -.->|"runs browser flow"| node_rpa_browser
node_n8n -->|"polls attachments"| node_gmail
node_n8n -->|"sends alerts"| node_slack
node_rpa_browser -->|"drives screening UI"| node_frontend
node_frontend -->|"uploads and matches"| node_router
node_router -->|"requests AI analysis"| node_groq
node_router -->|"persists screening data"| node_postgres
node_n8n -->|"starts browser run"| node_rpa_endpoint
node_n8n -->|"opens Slack view"| node_rpa_endpoint

click node_app "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/main.py"
click node_router "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/api/v1/api.py"
click node_endpoints "https://github.com/aliashrafabbasi/hireflow-ai-backend/tree/main/app/api/v1/endpoints"
click node_auth "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/dependencies/auth.py"
click node_auth_service "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/auth.py"
click node_user_repo "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/repositories/user.py"
click node_db_session "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/db/session.py"
click node_user_model "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/models/user.py"
click node_resume_model "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/models/resume.py"
click node_match_model "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/models/match_result.py"
click node_resume_service "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/resume.py"
click node_resume_parser "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/resume_parser.py"
click node_resume_analyzer "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/resume_analyzer.py"
click node_llm "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/llm.py"
click node_job_service "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/job.py"
click node_matching "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/matching.py"
click node_match_analyzer "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/match_analyzer.py"
click node_match_repo "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/repositories/match_result.py"
click node_career "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/career.py"
click node_rpa_endpoint "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/api/v1/endpoints/rpa.py"
click node_rpa_browser "https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/rpa_browser.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_router,node_endpoints,node_frontend toneBlue
class node_resume_service,node_resume_parser,node_resume_analyzer,node_llm,node_postgres toneAmber
class node_job_service,node_matching,node_match_analyzer,node_match_repo toneMint
class node_auth,node_auth_service,node_user_repo,node_db_session,node_user_model,node_resume_model,node_match_model toneRose
class node_career,node_rpa_endpoint,node_rpa_browser,node_actors,node_n8n,node_gmail,node_slack,node_groq toneIndigo
```

## Components

### API and access

- [Application startup](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/main.py): `app/main.py`
- [API router](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/api/v1/api.py): `app/api/v1/api.py`
- [API endpoints](https://github.com/aliashrafabbasi/hireflow-ai-backend/tree/main/app/api/v1/endpoints): `app/api/v1/endpoints`

### Resume screening

- [Resume management](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/resume.py): `app/services/resume.py`
- [Resume parsing](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/resume_parser.py): `app/services/resume_parser.py`
- [Resume analysis](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/resume_analyzer.py): `app/services/resume_analyzer.py`
- [LLM client](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/llm.py): `app/services/llm.py`

### Jobs and matching

- [Job management](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/job.py): `app/services/job.py`
- [Match engine](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/matching.py): `app/services/matching.py`
- [Match analysis](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/match_analyzer.py): `app/services/match_analyzer.py`
- [Match results repository](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/repositories/match_result.py): `app/repositories/match_result.py`

### Persistence and identity

- [JWT and role access](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/dependencies/auth.py): `app/dependencies/auth.py`
- [Account service](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/auth.py): `app/services/auth.py`
- [User repository](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/repositories/user.py): `app/repositories/user.py`
- [Database sessions](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/db/session.py): `app/db/session.py`
- [User records](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/models/user.py): `app/models/user.py`
- [Resume records](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/models/resume.py): `app/models/resume.py`
- [Match records](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/models/match_result.py): `app/models/match_result.py`

### Career and automation

- [Career portal services](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/career.py): `app/services/career.py`
- [RPA endpoints](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/api/v1/endpoints/rpa.py): `app/api/v1/endpoints/rpa.py`
- [Visible browser RPA](https://github.com/aliashrafabbasi/hireflow-ai-backend/blob/main/app/services/rpa_browser.py): `app/services/rpa_browser.py`

### Other components

- **Staff and candidates**
- **n8n workflow**
- **Gmail inbox**
- **Slack**
- **HireFlow frontend**
- **Groq LLM**
- **PostgreSQL**

## Connections

- Staff and candidates → API router: use API (evidence: `README.md`)
- n8n workflow → API router: invoke automation (evidence: `README.md`)
- Application startup → API router: mounts routes (evidence: `app/main.py`)
- API router → API endpoints: registers routes (evidence: `app/api/v1/api.py`)
- API endpoints → JWT and role access: protects requests (evidence: `app/api/v1/endpoints/admin.py`)
- API endpoints → Account service: handles accounts (evidence: `app/api/v1/endpoints/auth.py`)
- JWT and role access → User repository: loads user (evidence: `app/dependencies/auth.py`)
- Account service → User repository: manages accounts (evidence: `app/services/auth.py`)
- User repository → User records: queries users (evidence: `app/repositories/user.py`)
- API endpoints → Resume management: handles resumes (evidence: `app/api/v1/endpoints/resume.py`)
- API endpoints → Match engine: requests scores (evidence: `app/api/v1/endpoints/match.py`)
- API endpoints → Resume management: career resume actions (evidence: `app/api/v1/endpoints/user_career.py`)
- API endpoints → Career portal services: career portal requests (evidence: `app/api/v1/endpoints/user_career.py`)
- Resume management → Resume parsing: parses uploads
- Resume parsing → Resume analysis: analyzes text (evidence: `app/services/resume_parser.py`)
- Resume analysis → LLM client: requests analysis (evidence: `app/services/resume_analyzer.py`)
- LLM client → Groq LLM: sends prompts (evidence: `app/services/llm.py`)
- API endpoints → Job management: manages jobs (evidence: `app/api/v1/endpoints/jobs.py`)
- Job management → Groq LLM: analyzes descriptions
- Match engine → Match analysis: delegates analysis (evidence: `app/services/matching.py`)
- Match engine → Match results repository: reads and saves (evidence: `app/services/matching.py`)
- Match results repository → Match records: persists results (evidence: `app/repositories/match_result.py`)
- Resume management → Resume records: stores resumes
- Database sessions → PostgreSQL: opens sessions (evidence: `README.md`)
- RPA endpoints → Visible browser RPA: runs browser flow
- n8n workflow → Gmail inbox: polls attachments (evidence: `README.md`)
- n8n workflow → Slack: sends alerts (evidence: `README.md`)
- Visible browser RPA → HireFlow frontend: drives screening UI (evidence: `README.md`)
- HireFlow frontend → API router: uploads and matches (evidence: `README.md`)
- API router → Groq LLM: requests AI analysis (evidence: `README.md`)
- API router → PostgreSQL: persists screening data (evidence: `README.md`)
- n8n workflow → RPA endpoints: starts browser run (evidence: `README.md`)
- n8n workflow → RPA endpoints: opens Slack view (evidence: `README.md`)