# seadmustafa/jobfinder architecture

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

- Interactive diagram: https://gitdiagram.com/seadmustafa/jobfinder
- Repository: https://github.com/seadmustafa/jobfinder

## Overview

##### Project type and purpose
- Type: A backend-only Spring Boot integration service (no UI) that fetches job postings, analyzes them via AI, stores them in a database, and pushes alerts via WhatsApp.
- Purpose: Automate job discovery, AI-powered summarization, and real-time messaging on WhatsApp using Spring AI, Twilio, and PostgreSQL.

##### File structure
- MVC / Layered pattern:
- Controller layer: src/main/java/com/ai/finder/controller/JobController.java
- Service layer: multiple services in src/main/java/com/ai/finder/service
- Data access layer: src/main/java/com/ai/finder/repository + entity in entity/
- AI integration: src/main/java/com/ai/finder/ai/ChatClient, Prompt, ChatResponse
- Config: OpenApiConfig for Swagger/OpenAPI docs
- No frontend folder → purely backend microservice
- Build/deployment: pom.xml, Maven wrapper, application.properties for env injection

##### Extract insights from README
- Core tech: Java 17, Spring Boot, Spring AI, Twilio WhatsApp API, PostgreSQL, Maven
- Features: Web scraping job boards, summarization via OpenAI, persistence, WhatsApp delivery
- External dependencies: OpenAI API, Twilio Business API, Postgres DB
- Env vars used for secrets (DB, TWILIO, OPENAI)

##### Main components & interactions
a. Components:
1. JobController (REST endpoint or scheduler trigger)
2. WebScrapingService (fetch postings from external job boards over HTTP/HTML)
3. JobFinderService (orchestrates scraping → analysis → persistence → messaging)
4. JobAnalysisService (prepares prompts, calls ChatClient)
5. ChatClient (communicates with OpenAI API)
6. WhatsAppService (wraps Twilio’s WhatsApp API)
7. JobRepository / JPA + PostgreSQL (persistent store)
8. OpenAPI UI (Swagger docs via OpenApiConfig)
9. External systems: Job boards, OpenAI API, Twilio WhatsApp API, User’s WhatsApp client

b. Relationships & data flow:
1. Client (or internal scheduler) → HTTP request → JobController
2. JobController → JobFinderService
3. JobFinderService → WebScrapingService → Job postings
4. Persist raw postings → JobRepository → PostgreSQL
5. JobFinderService → JobAnalysisService → ChatClient → OpenAI API → summarized data
6. JobFinderService → WhatsAppService → Twilio WhatsApp API → end-user WhatsApp
7. Controller also exposes GET/POST endpoints for manual triggers or status checks
8. OpenAPI UI available at /swagger-ui.html

c. Architectural patterns & principles:
- Layered (Controller → Service → Repository)
- Dependency Injection (Spring-managed beans)
- Externalized configuration (env vars in application.properties)
- Single-responsibility per service (scraping vs. analysis vs. messaging)
- Integration with 3rd-party APIs via dedicated client classes

d. Key technologies:
- Spring Boot (application runtime)
- Spring AI (OpenAI integration)
- Spring Data JPA (JobRepository + PostgreSQL)
- Twilio Java SDK (WhatsAppService)
- Maven (build & dependency management)
- OpenAPI / Swagger (OpenApiConfig)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Application entry
    Application["JobfinderApplication"]:::config
    click Application "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/JobfinderApplication.java"

    %% Presentation Layer
    subgraph "Presentation Layer"
        Controller["JobController"]:::controller
        click Controller "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/controller/JobController.java"
    end

    %% Business Layer
    subgraph "Business Layer"
        FinderService["JobFinderService"]:::service
        click FinderService "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/service/JobFinderService.java"
        ScrapingService["WebScrapingService"]:::service
        click ScrapingService "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/service/WebScrapingService.java"
        AnalysisService["JobAnalysisService"]:::service
        click AnalysisService "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/service/JobAnalysisService.java"
        WhatsAppService["WhatsAppService"]:::service
        click WhatsAppService "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/service/WhatsAppService.java"
    end

    %% Data Access Layer
    subgraph "Data Access Layer"
        Repository["JobRepository"]:::repository
        click Repository "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/repository/JobRepository.java"
        Entity["Job"]:::entity
        click Entity "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/entity/Job.java"
        DB[(PostgreSQL)]:::db
    end

    %% Integration Layer
    subgraph "Integration Layer"
        ChatClient["ChatClient"]:::ai
        click ChatClient "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/ai/ChatClient.java"
        Prompt["Prompt"]:::ai
        click Prompt "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/ai/Prompt.java"
        Response["ChatResponse"]:::ai
        click Response "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/ai/ChatResponse.java"
        Config["OpenApiConfig"]:::config
        click Config "https://github.com/seadmustafa/jobfinder/blob/master/src/main/java/com/ai/finder/config/OpenApiConfig.java"
        Props["application.properties"]:::config
        click Props "https://github.com/seadmustafa/jobfinder/blob/master/src/main/resources/application.properties"
    end

    %% External Systems
    JobBoards["Job Boards"]:::external
    OpenAI["OpenAI API"]:::external
    TwilioAPI["Twilio WhatsApp API"]:::external
    UserWhatsApp["User WhatsApp Client"]:::external

    %% Relationships
    Application -->|starts| Controller
    Controller -->|trigger| FinderService
    FinderService -->|scrape| ScrapingService
    ScrapingService -->|data| Repository
    Repository -->|save/read| DB
    FinderService -->|raw data| AnalysisService
    AnalysisService -->|build prompt| Prompt
    AnalysisService -->|send request| ChatClient
    ChatClient -->|call API| OpenAI
    OpenAI -->|response| ChatClient
    ChatClient -->|return summary| Response
    FinderService -->|summary| WhatsAppService
    WhatsAppService -->|send message| TwilioAPI
    TwilioAPI -->|deliver| UserWhatsApp
    Controller -->|docs| Config

    %% External connections
    ScrapingService -->|fetch| JobBoards

    %% Styles
    classDef controller fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef service fill:#87CEFA,stroke:#333,stroke-width:1px
    classDef repository fill:#FFD580,stroke:#333,stroke-width:1px
    classDef entity fill:#FFE4B5,stroke:#333,stroke-width:1px
    classDef ai fill:#D8BFD8,stroke:#333,stroke-width:1px
    classDef config fill:#D3D3D3,stroke:#333,stroke-width:1px
    classDef db fill:#FFA500,stroke:#333,stroke-width:1px,shape:cylinder
    classDef external fill:#98FB98,stroke:#333,stroke-width:1px
```
