# theihasan/geezap architecture

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

- Interactive diagram: https://gitdiagram.com/theihasan/geezap
- Repository: https://github.com/theihasan/geezap

## Overview

##### Main System Components

a) Client Layer
- Web Interface (Built with Livewire + TailwindCSS)
- Admin Panel (Filament-based)

b) Application Layer
- Authentication System
- Job Management System
- Cover Letter Generation System
- WebSocket System (Laravel Reverb)
- Queue System

c) Integration Layer
- External Job Platforms (LinkedIn, Upwork, Indeed, ZipRecruiter)
- OpenAI API Integration
- Social Auth Providers
- Cloudflare Turnstile

d) Data Layer
- MySQL Database
- Cache System
- File Storage

##### Component Relationships

a) Frontend to Backend:
- HTTP/HTTPS requests between web clients and controllers
- WebSocket connections for real-time updates
- API endpoints for job data and cover letter generation

b) Internal Services:
- Queue system handling background jobs (GenerateCoverLetterJob, GetJobData)
- Event system managing notifications (CoverLetterGenerated event)
- Service classes managing business logic (AIService, MetaTagGenerator)

c) External Integrations:
- API connections to job platforms
- OpenAI API for cover letter generation
- Social authentication providers

##### Specific Implementation Details

a) Core Features:
**Web Client -> JobController -> JobFilter Pipeline -> External Job APIs**
**User -> CoverLetterController -> AIService -> OpenAI API**
**Admin Panel -> Filament Resources -> Database**

b) Authentication Flow:
**User -> SocialAuthController -> External Providers**
**User -> AuthenticatedSessionController -> Database**

c) Real-time Features:
**Client -> Laravel Reverb -> WebSocket Server**

##### Important Architectural Patterns to Highlight

- MVC Pattern (Controllers, Models, Views structure)
- Repository Pattern (Job data handling)
- Observer Pattern (JobListingObserver, UserObserver)
- DTO Pattern (Multiple DTOs for data transfer)
- Queue-based Architecture (Background jobs)

##### Key Technical Components

Specific elements:

- Filament Admin Panel (/app/Filament)
- Job Management System (/app/Http/Controllers/JobController)
- Cover Letter Generation (/app/Services/AIService)
- Authentication System (/app/Http/Controllers/Auth)
- Queue Workers (/app/Jobs)
- WebSocket Server (Laravel Reverb)

**User Request -> Controller -> Service -> External API -> Database**
**Job Fetch -> Queue -> Job Processing -> Database -> WebSocket -> Client**
**Cover Letter Request -> Queue -> AI Service -> OpenAI -> Database**

##### Infrastructure Components

Include:

- MySQL Database
- Redis/Cache Server
- Queue Worker Processes
- WebSocket Server
- File Storage System

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Client Layer"
        WI[Web Interface<br/>Livewire + TailwindCSS]
        AP[Admin Panel<br/>Filament-based]
        WI --> AP
    end

    subgraph "Application Layer"
        AS[Authentication System<br/>Session & Social Auth]
        JMS[Job Management System<br/>CRUD & Filters]
        CLS[Cover Letter System<br/>AI Generation]
        WS[WebSocket System<br/>Laravel Reverb]
        QS[Queue System<br/>Background Jobs]
    end

    subgraph "Integration Layer"
        direction TB
        EJP[External Job Platforms<br/>LinkedIn, Upwork, Indeed]
        OAI[OpenAI API<br/>GPT Integration]
        SAP[Social Auth Providers<br/>OAuth2]
        CFT[Cloudflare Turnstile<br/>Bot Protection]
    end

    subgraph "Data Layer"
        DB[(MySQL Database<br/>User & Job Data)]
        CS[(Cache System<br/>Redis)]
        FS[(File Storage<br/>Documents & Media)]
    end

    subgraph "Service Layer"
        MTS[Meta Tag Service<br/>SEO Optimization]
        PS[Profile Service<br/>User Management]
        SAS[Social Auth Service<br/>OAuth Handlers]
        AIS[AI Service<br/>OpenAI Integration]
    end

    WI -->|"HTTP/WS"| AS
    WI -->|"CRUD Operations"| JMS
    WI -->|"Real-time Updates"| WS
    AP -->|"Admin Controls"| JMS

    AS -->|"Auth Jobs"| QS
    JMS -->|"Job Processing"| QS
    CLS -->|"Generation Tasks"| QS
    QS -->|"Event Broadcasting"| WS

    JMS -->|"API Calls"| EJP
    CLS -->|"AI Requests"| OAI
    AS -->|"OAuth Flow"| SAP
    WI -->|"Verification"| CFT

    JMS -->|"CRUD"| DB
    CLS -->|"Store Results"| DB
    AS -->|"User Data"| DB
    QS -->|"Job States"| CS
    JMS -->|"Attachments"| FS

    JMS -->|"SEO Generation"| MTS
    AS -->|"User Management"| PS
    AS -->|"OAuth Processing"| SAS
    CLS -->|"GPT Integration"| AIS

    classDef default fill:#f9f9f9,stroke:#333,stroke-width:2px
    classDef external fill:#90EE90,stroke:#333
    classDef database fill:#DCDCDC,stroke:#333
    classDef service fill:#ADD8E6,stroke:#333
    classDef queue fill:#FFA500,stroke:#333
    classDef websocket fill:#DDA0DD,stroke:#333

    class EJP,OAI,SAP,CFT external
    class DB,CS,FS database
    class MTS,PS,SAS,AIS service
    class QS queue
    class WS websocket

    click WI "https://github.com/theihasan/geezap/tree/main/app/Livewire/"
    click AP "https://github.com/theihasan/geezap/tree/main/app/Filament/Resources/"
    click AS "https://github.com/theihasan/geezap/tree/main/app/Http/Controllers/Auth/"
    click JMS "https://github.com/theihasan/geezap/blob/main/app/Http/Controllers/JobController.php"
    click CLS "https://github.com/theihasan/geezap/blob/main/app/Services/AIService.php"
    click WS "https://github.com/theihasan/geezap/blob/main/config/reverb.php"
    click QS "https://github.com/theihasan/geezap/tree/main/app/Jobs/"
    click SAS "https://github.com/theihasan/geezap/blob/main/app/Services/SocialAuthService.php"
    click CFT "https://github.com/theihasan/geezap/blob/main/app/Http/Middleware/VerifyClouflareTurnstile.php"
    click MTS "https://github.com/theihasan/geezap/blob/main/app/Services/MetaTagGenerator.php"
    click PS "https://github.com/theihasan/geezap/blob/main/app/Services/ProfileService.php"
    click DB "https://github.com/theihasan/geezap/tree/main/database/migrations/"
    click AIS "https://github.com/theihasan/geezap/blob/main/app/Services/AIService.php"
```
