# sanjjayrj/job-aggregator-conversational-gen-ai-agent architecture

> Architecture diagram of the GitHub repository sanjjayrj/job-aggregator-conversational-gen-ai-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sanjjayrj/job-aggregator-conversational-gen-ai-agent
- Repository: https://github.com/sanjjayrj/job-aggregator-conversational-gen-ai-agent

## Overview

##### Project Type and Purpose
- This project is a full-stack web application focused on dynamic job recommendations. It lets users upload resumes, scrapes job listings from external sources, parses and processes these inputs, and then uses OpenAI embeddings to match jobs with the user's profile.
- Key functionalities include resume parsing, job scraping, embedding generation and matching, geographical filtering, and an integrated chatbot assistant for interactive job queries.

##### File Structure
- Top-level files like app.py, matcher.py, parser.py, and scraper.py indicate that most of the core functionality is managed from Python modules in a Flask backend.
- The “static” directory (with CSS and assets) and “templates” folder (with HTML files) represent the frontend components.
- The presence of configuration files such as requirements.txt and .gitignore, along with README.md, points to standard best practices.
- Data persistence appears to be handled via several files that are generated at runtime (CSV for job listings, JSON files for parsed resumes, embeddings, and job recommendations).

##### Main Components
a. Frontend:
- User interface using HTML templates (in the “templates” directory) and styling/CSS assets (in the “static” directory).
- This is where users interact with the system—uploading resumes, setting preferences, and interacting with the chat interface.

b. Flask Backend (app.py):
- Acts as the main controller, handling HTTP routes and coordinating between different modules.
- Manages user sessions, API endpoints, and serving the frontend.

c. Resume Parser (parser.py):
- Handles resume upload, parsing, and saving the extracted text to a JSON file.

d. Job Scraper (scraper.py):
- Responsible for retrieving job listings from external sites (like Indeed) and appending them to a CSV while managing duplicates.

e. Job Matcher/Embedding Generator (matcher.py):
- Generates embeddings for both resumes and job descriptions using OpenAI’s embedding API.
- Performs matching (e.g., cosine similarity) between user resumes and scraped job data.

f. Data Storage:
- Use files such as CSV (job_listings.csv) and JSON files (parsed_resume.json, job_embeddings.json, top_jobs.json) as lightweight databases.

g. External APIs & Services:
- OpenAI API: For generating embeddings and powering the chatbot.
- Nominatim (OpenStreetMap API) & geopy: For geocoding and distance calculations.

h. Chatbot Assistant:
- Integrated with the Flask backend to process user input via the chat interface (embedded in HTML/JavaScript) and respond with help, career advice, or trigger new job scraping/matching operations.

##### Relationships and Interactions
- User interactions through the Frontend will initiate HTTP requests to the Flask backend.
- The backend routes (in app.py) coordinate calls to parser.py for processing uploaded resumes, scraper.py for pulling job listings, and matcher.py for generating embeddings and matching.
- The matching module uses data stored in CSV and JSON files to process results and sends refined recommendations back to the frontend.
- External API calls (to OpenAI and Nominatim) are made from within the backend modules, contributing to job matching and geographical filtering.

##### Architectural Patterns and Key Technologies
- The overall design follows a Model-View-Controller (MVC) pattern, where:
- The “View” is represented by the HTML & CSS in the templates and static directories.
- The “Controller” is managed by Flask in app.py.
- “Models” (in a loose sense) are the data representations stored in CSV/JSON and handled by parser.py, scraper.py, and matcher.py.
- The integration of asynchronous operations (for scraping/updating job recommendations) highlights a real-time update pattern.
- From the User Interface to Flask routes.
- From Flask to each processing module (parser, scraper, matcher).
- From these modules to external APIs and local file stores.

- Use clear text labels for each element.
- User → Frontend (templates/JavaScript) → Backend (app.py).
- Backend → Resume Parser, Job Scraper, Job Matcher.
- Backend ↔ External APIs (OpenAI, Nominatim).
- Backend → Data Stores (CSV and JSON files).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    U("User"):::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        FT("Templates (HTML)"):::frontend
        FS("Static Assets (CSS)"):::frontend
    end

    %% Backend Layer
    subgraph "Backend Layer"
        FB("Flask Backend (app.py)"):::backend
        RP("Resume Parser (parser.py)"):::backend
        JS("Job Scraper (scraper.py)"):::backend
        JM("Job Matcher (matcher.py)"):::backend
        CB("Chatbot Assistant"):::backend
    end

    %% External Services
    subgraph "External APIs & Services"
        OA("OpenAI API"):::external
        NM("Nominatim/Geopy"):::external
    end

    %% Data Storage
    subgraph "Data Storage"
        CSV("CSV Files"):::storage
        JSON("JSON Files"):::storage
    end

    %% Data Flow Connections
    U -->|"interacts"| FT
    U -->|"interacts"| FS
    FT -->|"sends requests"| FB
    FS -->|"sends requests"| FB

    FB -->|"calls"| RP
    FB -->|"calls"| JS
    FB -->|"calls"| JM
    FB -->|"coordinates"| CB

    RP -->|"writes parsed data"| JSON
    JS -->|"writes job listings"| CSV
    JM -->|"reads from"| JSON
    JM -->|"reads from"| CSV

    FB -->|"calls"| OA
    JM -->|"calls"| OA
    FB -->|"calls"| NM

    CB -->|"triggers updates"| FB

    %% Click Events
    click FT "https://github.com/sanjjayrj/job-aggregator-conversational-gen-ai-agent/tree/main//templates"
    click FS "https://github.com/sanjjayrj/job-aggregator-conversational-gen-ai-agent/tree/main//static"
    click FB "https://github.com/sanjjayrj/job-aggregator-conversational-gen-ai-agent/blob/main//app.py"
    click RP "https://github.com/sanjjayrj/job-aggregator-conversational-gen-ai-agent/blob/main//parser.py"
    click JS "https://github.com/sanjjayrj/job-aggregator-conversational-gen-ai-agent/blob/main//scraper.py"
    click JM "https://github.com/sanjjayrj/job-aggregator-conversational-gen-ai-agent/blob/main//matcher.py"

    %% Styles / Classes
    classDef user fill:#fef9c3,stroke:#f59e0b,stroke-width:2px;
    classDef frontend fill:#93c5fd,stroke:#2563eb,stroke-width:2px;
    classDef backend fill:#a7f3d0,stroke:#059669,stroke-width:2px;
    classDef external fill:#fed7aa,stroke:#ea580c,stroke-width:2px;
    classDef storage fill:#e5e7eb,stroke:#6b7280,stroke-width:2px;
```
