# mahithabsl/ai-powered-hr-assistant architecture

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

- Interactive diagram: https://gitdiagram.com/mahithabsl/ai-powered-hr-assistant
- Repository: https://github.com/mahithabsl/ai-powered-hr-assistant

## Overview

##### Project Type and Purpose
- This is a domain-specific, full-stack data pipeline and question-answering application for HR, named “AI-Powered-HR-Assistant” (Graph-RAG).
- It processes PDF resumes into structured data, constructs a knowledge graph in Neo4j, and offers two interfaces:
- An interactive Streamlit chatbot UI for graph-based QA
- Jupyter notebooks for interview-question generation and metadata exploration.

##### File Structure Analysis
- Top-level scripts and notebooks:
- Pdf_2_Text.py: PDF ingestion and text extraction
- MetaData_Extraction.ipynb: Structured metadata extraction from text
- Pdf_2_Graph.py: Graph construction into Neo4j
- Graph_QA.py: Streamlit app for graph-based QA
- Generate_Interview_Questions.ipynb: Interview Q generation
- Data folder:
- data/resumes: raw PDF resumes
- data/metadata: metadata spreadsheets
- data/resume_data.csv: intermediate CSV
- Configuration:
- config.ini: Neo4j credentials, API keys, PDF processing parameters
- Static assets: images/css for the UI in static/

##### Key Components
- Frontend: Streamlit-based Chatbot UI
- Backend services:
- PDF Processing Module (Pdf_2_Text)
- Metadata Extraction Notebook/Module
- Graph Builder Module (Pdf_2_Graph)
- QA Module (Graph_QA)
- Interview Question Generation (notebook)
- Database: Neo4j graph database
- External Services:
- LLM Providers (OpenAI, Groq, Ollama)
- Embedding Providers (Cohere, OpenAI, Ollama)
- Storage:
- Local file system (PDFs, CSV, Excel metadata)

##### Relationships and Data Flows
- PDF files → Pdf_2_Text → raw text
- Raw text → MetaData_Extraction → structured JSON/CSV
- Structured data + PDFs → Pdf_2_Graph → Neo4j
- Streamlit UI / Graph_QA:
- Retrieved data → LLM (RAG) → generated answer → UI
- Interview Q Gen notebook calls APIs/graph to produce questions

##### Architectural Patterns and Design Principles
- Modular pipeline: each stage isolated (ingestion, extraction, graphing, QA)
- RAG pattern: retrieval from graph + generative LLM
- Layered design: UI layer, processing layer, persistence layer, external services
- Config-driven: all credentials and parameters in config.ini

##### Essential Elements
- Arrowheads indicating data flow direction
- Annotations for protocols (e.g., Bolt, HTTP, API calls)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Storage Layer
    subgraph "Storage"
        Resumes["data/resumes/"]:::storage
        MetadataExcel["METADATA-FINAL.xlsx"]:::storage
        MetadataCSV["resume_data.csv"]:::storage
        Config["config.ini"]:::storage
        StaticAssets["static/"]:::storage
        Neo4jDB["Neo4j Database"]:::db
    end

    %% Processing Pipeline
    subgraph "Processing Layer"
        PdfProc["Pdf_2_Text.py"]:::process
        MetaExtract["MetaData_Extraction.ipynb"]:::process
        GraphBuild["Pdf_2_Graph.py"]:::process
    end

    %% UI Layer
    subgraph "UI Layer"
        StreamlitUI["Graph_QA.py"]:::frontend
    end

    %% Analysis & Authoring
    subgraph "Analysis & Authoring"
        IQGen["Generate_Interview_Questions.ipynb"]:::process
    end

    %% External Services
    subgraph "External Services"
        LLM["LLM Providers"]:::external
        Embed["Embedding Providers"]:::external
    end

    %% Data Flows
    Resumes -->|"PDF input"| PdfProc
    PdfProc -->|"raw text output"| MetaExtract
    MetaExtract -->|"metadata CSV"| MetadataCSV
    MetaExtract -->|"metadata Excel"| MetadataExcel
    Resumes -->|"raw PDFs"| GraphBuild
    MetadataCSV -->|"structured data"| GraphBuild
    GraphBuild -->|"ingest via Bolt"| Neo4jDB
    StreamlitUI -->|"Bolt queries"| Neo4jDB
    Neo4jDB -->|"subgraph data"| StreamlitUI
    StreamlitUI -->|"RAG API calls"| LLM
    LLM -->|"generated answers"| StreamlitUI
    StreamlitUI -->|"embedding requests"| Embed
    IQGen -->|"graph queries"| Neo4jDB

    %% Configuration dependencies
    Config -.-> PdfProc
    Config -.-> MetaExtract
    Config -.-> GraphBuild
    Config -.-> StreamlitUI
    Config -.-> IQGen

    %% Click Events
    click PdfProc "https://github.com/mahithabsl/ai-powered-hr-assistant/blob/main/Pdf_2_Text.py"
    click MetaExtract "https://github.com/mahithabsl/ai-powered-hr-assistant/blob/main/MetaData_Extraction.ipynb"
    click GraphBuild "https://github.com/mahithabsl/ai-powered-hr-assistant/blob/main/Pdf_2_Graph.py"
    click StreamlitUI "https://github.com/mahithabsl/ai-powered-hr-assistant/blob/main/Graph_QA.py"
    click IQGen "https://github.com/mahithabsl/ai-powered-hr-assistant/blob/main/Generate_Interview_Questions.ipynb"
    click Config "https://github.com/mahithabsl/ai-powered-hr-assistant/blob/main/config.ini"
    click Resumes "https://github.com/mahithabsl/ai-powered-hr-assistant/tree/main/data/resumes/"
    click MetadataExcel "https://github.com/mahithabsl/ai-powered-hr-assistant/blob/main/data/metadata/METADATA-FINAL.xlsx"
    click MetadataCSV "https://github.com/mahithabsl/ai-powered-hr-assistant/blob/main/data/metadata/resume_data.csv"
    click StaticAssets "https://github.com/mahithabsl/ai-powered-hr-assistant/tree/main/static/"

    %% Styling
    classDef process fill:#cce5ff,stroke:#007bff,stroke-width:1px
    classDef frontend fill:#d4edda,stroke:#28a745,stroke-width:1px
    classDef db fill:#d4edda,stroke:#28a745,stroke-width:1px,stroke-dasharray: 5 5
    classDef external fill:#ffe5b4,stroke:#ff8c00,stroke-width:1px
    classDef storage fill:#e2e3e5,stroke:#6c757d,stroke-width:1px
```
