# hazzanzz/ai-powered-resume-ranker architecture

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

- Interactive diagram: https://gitdiagram.com/hazzanzz/ai-powered-resume-ranker
- Repository: https://github.com/hazzanzz/ai-powered-resume-ranker

## Overview

##### Project type and purpose
- This is a lightweight full-stack application built with Streamlit (Python) that ranks and improves resumes.
- It ingests two inputs (resume PDF, job description TXT), applies NLP (SBERT, YAKE), and calls an external AI service (OpenAI ChatGPT) to produce scores, keyword comparisons, and improvement suggestions.

##### File structure
- app.py
- The Streamlit entry point (frontend + controller).
- resume_matcher.py
- Encapsulates semantic similarity logic (SBERT).
- keyword_extractor.py
- Encapsulates YAKE keyword extraction.
- chatgpt_improver.py
- Wraps OpenAI ChatGPT API calls for improvement suggestions.
- job_description.txt, sample_data/randomized-resume.pdf
- Sample inputs.
- test_keywords.py, test_similarity.py
- Unit tests for core NLP modules.
- requirements.txt
- Lists Python dependencies.
- secret.gitignore
- Hides API keys.

##### README for additional insights
- Tech stack: Streamlit frontend, SBERT, YAKE, PyPDF2, OpenAI API.
- Features: PDF parsing → semantic similarity → keyword extraction → ChatGPT suggestions.

##### Main components & their interactions
a. Components
1. User Interface (Streamlit app.py)
2. PDF/Text Ingestion (PyPDF2 in app.py)
3. Keyword Extractor (keyword_extractor.py with YAKE)
4. Semantic Similarity Processor (resume_matcher.py with SBERT)
5. AI Improver (chatgpt_improver.py calling OpenAI API)
6. Data Stores (in-memory or local file I/O for inputs; no persistent DB)
7. External Service (OpenAI ChatGPT API)
b. Interactions
- User uploads resume & job description → Streamlit UI
- app.py invokes PDF/Text Ingestion → raw text
- Text passes in parallel to Keyword Extractor and Semantic Similarity Processor
- Results aggregated (match % + top keywords)
- If user requests improvements, app.py calls AI Improver → OpenAI API → suggestions
- Final output rendered back to Streamlit UI
c. Architectural patterns / design principles
- Modular separation: each NLP task is encapsulated in its own module
- “Controller” (app.py) orchestrates data flow
- Stateless processing: each request runs pipeline from scratch
- External dependency isolation: secrets in .gitignore
d. Key technologies
- Streamlit (frontend & minimal server)
- PyPDF2 (PDF parsing)
- SBERT via sentence-transformers (semantic similarity)
- YAKE (keyword extraction)
- OpenAI API (ChatGPT enhancements)
- pytest (unit tests)

##### Detailed elements
- Component names (e.g., app.py: Streamlit Controller)
- Data stores/inputs (resume PDF, JD TXT)
- OpenAI ChatGPT with API key (secret management)

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "Inputs"
        JD["Job Description TXT"]:::io
        Resume["Resume PDF"]:::io
    end

    subgraph "Frontend (Streamlit)"
        UI["app.py\n(Streamlit Controller)"]:::frontend
    end

    subgraph "Ingestion"
        Ingest["PDF/Text Ingestion\n(PyPDF2)"]:::processing
    end

    subgraph "NLP Modules"
        KE["Keyword Extractor\n(keyword_extractor.py)"]:::processing
        SS["Semantic Similarity Processor\n(resume_matcher.py)"]:::processing
    end

    Aggregator["Results Aggregation"]:::processing

    AIImp["AI Improver\n(chatgpt_improver.py)"]:::processing

    subgraph "External Service"
        OpenAI["OpenAI ChatGPT API"]:::external
    end

    subgraph "Configuration & Management"
        Secrets["secret.gitignore"]:::config
        Req["requirements.txt"]:::config
        Readme["README.md"]:::config
    end

    subgraph "Tests"
        TK["test_keywords.py"]:::test
        TS["test_similarity.py"]:::test
    end

    JD -->|upload| UI
    Resume -->|upload| UI
    UI -->|extract text| Ingest
    Ingest -->|text| KE
    Ingest -->|text| SS
    KE -->|keywords| Aggregator
    SS -->|score| Aggregator
    Aggregator -->|results| UI
    UI -->|improve request| AIImp
    AIImp -->|API request| OpenAI
    OpenAI -->|suggestions| AIImp
    AIImp -->|suggestions| UI

    click UI "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/app.py"
    click Ingest "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/app.py"
    click KE "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/keyword_extractor.py"
    click SS "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/resume_matcher.py"
    click AIImp "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/chatgpt_improver.py"
    click JD "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/job_description.txt"
    click Resume "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/sample_data/randomized-resume.pdf"
    click Secrets "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/secret.gitignore"
    click Req "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/requirements.txt"
    click TK "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/test_keywords.py"
    click TS "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/test_similarity.py"
    click Readme "https://github.com/hazzanzz/ai-powered-resume-ranker/blob/main/README.md"

    classDef frontend fill:#bbdefb,stroke:#0d47a1,color:#0d47a1;
    classDef processing fill:#c8e6c9,stroke:#1b5e20,color:#1b5e20;
    classDef external fill:#ffe0b2,stroke:#e65100,color:#e65100;
    classDef io fill:#e3f2fd,stroke:#1565c0,color:#1565c0;
    classDef config fill:#eeeeee,stroke:#616161,color:#424242;
    classDef test fill:#f3e5f5,stroke:#6a1b9a,color:#4a148c;
```
