# kv-raghava/resume_ranking architecture

> Architecture diagram of the GitHub repository kv-raghava/resume_ranking, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kv-raghava/resume_ranking
- Repository: https://github.com/kv-raghava/resume_ranking

## Overview

##### Project Type and Purpose
- This is a lightweight, stateless microservice (full-stack backend API) for automating resume ranking.
- Purpose: Receive job descriptions and resumes over HTTP, use OpenAI to extract criteria and score resumes, then return JSON responses.

##### File Structure
- Top-level:
- app.py – main FastAPI application entry point
- requirements.txt / .env – dependency and configuration
- routes/criteria.py – endpoint for criteria extraction
- routes/scoring.py – endpoint for resume evaluation
- No persistent database: the service is request-driven and uses OpenAI as an external AI engine.

##### Extracted Insights from README
- Two POST endpoints:
- /extract-criteria
- /evaluate-resume
- Built with FastAPI and OpenAI’s API.
- Configuration via an environment variable (OPENAI_API_KEY).

##### Main Components & Their Interactions
a. Client (could be a web UI, CLI, or Postman):
- Sends HTTP POST requests with job description or resume payloads.
b. FastAPI Server (app.py):
- Hosts the HTTP server, routes incoming requests.
c. Route Handlers:
- criteria.py – orchestrates extracting criteria logic
- scoring.py – orchestrates resume evaluation logic
d. OpenAI External Service:
- Invoked by route handlers using the OPENAI_API_KEY to perform LLM operations.
e. Environment & Config:
- .env file provides the API key; requirements.txt pins dependencies.

##### Relationships & Data Flows
1. Client → FastAPI (app.py)
2. FastAPI → Route Handler (criteria.py or scoring.py)
3. Route Handler → OpenAI API (external HTTPS call)
4. OpenAI API → Route Handler (returns JSON with criteria or score)
5. Route Handler → FastAPI → Client (JSON response)

##### Architectural Patterns & Principles
- Layered (Controller/Router layer, Service/integration layer).
- External facade (OpenAI API) treated as a microservice.
- Stateless design: no local DB; each request is independent.

## Diagram (Mermaid)

```mermaid
flowchart TD
    Client["Client"]:::client
    subgraph "API Server"
        APPS["app.py<br/>(FastAPI Server)"]:::internal
        CR["criteria.py<br/>(Criteria Route)"]:::internal
        SR["scoring.py<br/>(Scoring Route)"]:::internal
    end
    ENV[".env<br/>(OPENAI_API_KEY)"]:::config
    REQ["requirements.txt"]:::config
    DOC["README.md"]:::config
    OA["OpenAI API"]:::external

    Client -->|POST /extract-criteria<br/>jobDesc JSON| APPS
    APPS --> CR
    CR -->|HTTPS POST| OA
    OA --> CR
    CR --> APPS
    APPS -->|JSON Response| Client

    Client -->|POST /evaluate-resume<br/>resume JSON| APPS
    APPS --> SR
    SR -->|HTTPS POST| OA
    OA --> SR
    SR --> APPS
    APPS -->|JSON Response| Client

    APPS -. reads .-> ENV
    APPS -. reads .-> REQ
    DOC -. documents .-> APPS

    click APPS "https://github.com/kv-raghava/resume_ranking/blob/main/app.py"
    click CR "https://github.com/kv-raghava/resume_ranking/blob/main/routes/criteria.py"
    click SR "https://github.com/kv-raghava/resume_ranking/blob/main/routes/scoring.py"
    click ENV "https://github.com/kv-raghava/resume_ranking/blob/main/.env"
    click REQ "https://github.com/kv-raghava/resume_ranking/blob/main/requirements.txt"
    click DOC "https://github.com/kv-raghava/resume_ranking/blob/main/README.md"

    classDef internal fill:#bbdefb,stroke:#0d47a1,color:#0d47a1
    classDef external fill:#fff9c4,stroke:#fbc02d,color:#f57f17
    classDef config fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
    classDef client fill:#e0e0e0,stroke:#424242,color:#212121
```
