# faveosuite/faveo-helpdesk architecture

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

- Interactive diagram: https://gitdiagram.com/faveosuite/faveo-helpdesk
- Repository: https://github.com/faveosuite/faveo-helpdesk

## Overview

##### Project type and purpose
- This is a monolithic, full-stack web application built on Laravel (PHP 8.1) that provides a helpdesk / ticketing system.
- It exposes both browser-based UI (blade templates + JS/CSS assets) and a RESTful API (versions v1 & v2).

##### Key components
a. Clients
- Web browser (loads HTML, CSS, JS from public/)
- API consumers (mobile apps, external systems)
b. Web server & application runtime
- Apache or Nginx + PHP-FPM container
- Laravel framework layers:
– Route definitions (routes/web.php, routes/api.php, etc.)
– Middleware (auth, CSRF, JWT, roles)
– Controllers (Admin, Agent, Client, Api v1/v2, Installer, Update)
– Service Providers (AppServiceProvider, ApiServiceProvider, plugin providers)
– Events & Listeners (app/Events → app/Listeners)
– Console Commands & Scheduler (app/Console/Commands, artisan schedule)
– Queue Worker (jobs table, app/Jobs, queue worker process)
c. Persistence
- MySQL / MariaDB (managed via Eloquent models, migrations under database/migrations)
- File storage (attachments, logs) under storage/
d. External services
- SMTP/IMAP server for ticket emails (MailService, FaveoQueue)
- Bugsnag for error reporting
- Third-party integrations (Socialite for social login, external APIs)

##### Relationships & data flow
- Browser → HTTP request → Web server → Laravel router → Controller → Model/Eloquent → MySQL → Controller → Blade view → HTML response → Browser
- API client → /​api/v1 or /​api/v2 → TokenAuthController → Services → JSON response
- User actions (e.g., “Create Ticket”) dispatch an Event → Listener queues email jobs → jobs table → Queue worker picks up → SMTP sends email
- Cron scheduler runs artisan commands (e.g., TicketFetch) → Dispatches jobs or synchronizes updates
- File uploads saved to storage/app and served via public/vendor or symlink

##### Architectural patterns & design principles
- MVC (Models, Views, Controllers)
- Service-provider based modularization (core + plugins)
- Event-driven notifications and extensibility (app/Events & app/Listeners)
- Command Bus for console tasks (artisan commands)
- Dependency injection via Laravel’s service container
- Eloquent ORM with migrations & seeders for schema management

##### Technologies & frameworks
- Backend: PHP 8.1, Laravel (v9.x), MySQL/MariaDB
- Frontend: Blade templates, AdminLTE theme, jQuery, Angular2 snippets, CKEditor, Webpack (webpack.mix.js)
- Queue driver: database (jobs table) or Redis
- CI/CD: Travis CI, GitHub Actions, StyleCI, Scrutinizer

##### Don’t forget these details
- Both web and API routes
- Middleware checks (Auth, JWT) in the request path
- Plugin modules (app/Plugins, FaveoStorage, FaveoLog) as separate service provider blocks
- File upload/download to storage/app and serving from public/
- Event → listener → job pipelines for notifications

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Presentation Layer
    subgraph "Presentation Layer"
        direction TB
        WebBrowser["Web Browser"]:::requestflow
        APIClient["API Consumers"]:::requestflow
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        Router["Laravel Router"]:::requestflow
        Middleware["Middleware (Auth, CSRF, JWT)"]:::requestflow
        subgraph "Controllers"
            direction TB
            AdminCtrl["Admin Controllers"] 
            AgentCtrl["Agent Controllers"]
            ClientCtrl["Client Controllers"]
            InstallerCtrl["Installer Controllers"]
            UpdateCtrl["Update Controllers"]
        end
        subgraph "API Controllers"
            direction TB
            APIV1Ctrl["API v1 Controllers"]
            APIV2Ctrl["API v2 Controllers"]
        end
        subgraph "Service Providers"
            direction TB
            CoreProv["Core Service Providers"]
            APIProv["API Service Provider"]
            PluginProv["Plugin Service Providers"]
        end
        Events["Events"]:::async
        Listeners["Listeners"]:::async
        Models["Eloquent Models"]:::requestflow
        Migrations["Migrations"]:::requestflow
        Blade["Blade Templates & Views"]:::requestflow
        Assets["Assets & Frontend"]:::requestflow
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        MySQL[(MySQL/MariaDB)]:::requestflow
        FileStorage["File Storage"]:::requestflow
        PublicFiles["Public Files"]:::requestflow
    end

    %% Background Processing
    subgraph "Background Processing"
        direction TB
        Scheduler["Scheduler & Console"]:::async
        QueueWorker["Queue Worker & Jobs"]:::async
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SMTP["SMTP/IMAP"]:::external
        Bugsnag["Bugsnag"]:::external
        SocialAPIs["Socialite & External APIs"]:::external
    end

    %% Connections - Web UI Flow
    WebBrowser -->|"HTTP Request"| Router
    Router -->|passes through| Middleware
    Middleware -->|invokes| AdminCtrl
    Middleware -->|invokes| AgentCtrl
    Middleware -->|invokes| ClientCtrl
    AdminCtrl -->|uses| Models
    AgentCtrl -->|uses| Models
    ClientCtrl -->|uses| Models
    AdminCtrl -->|renders| Blade
    AgentCtrl -->|renders| Blade
    ClientCtrl -->|renders| Blade
    Blade -->|HTML Response| WebBrowser

    %% Connections - API Flow
    APIClient -->|"HTTPS Request /api/v1 or v2"| Router
    Router -->|passes through| Middleware
    Middleware -->|invokes| APIV1Ctrl
    Middleware -->|invokes| APIV2Ctrl
    APIV1Ctrl -->|uses| Models
    APIV2Ctrl -->|uses| Models
    APIV1Ctrl -->|JSON Response| APIClient
    APIV2Ctrl -->|JSON Response| APIClient

    %% Data interactions
    Models -->|DB Queries| MySQL
    Migrations -->|manage schema| MySQL

    %% File storage
    AdminCtrl -->|uploads/downloads| FileStorage
    FileStorage -->|served via symlink| PublicFiles
    PublicFiles -->|assets| WebBrowser

    %% Background flows
    AdminCtrl -->|dispatches Event| Events
    Events -->|handled by| Listeners
    Listeners -->|creates jobs| QueueWorker
    QueueWorker -->|sends email| SMTP

    Scheduler -->|artisan schedule| QueueWorker
    Scheduler -->|runs commands| AdminCtrl

    %% External
    APIProv -->|error reports| Bugsnag
    SocialAPIs -->|login| ClientCtrl

    %% Click Events
    click WebBrowser "https://github.com/faveosuite/faveo-helpdesk/blob/development/public/index.php"
    click WebBrowser "https://github.com/faveosuite/faveo-helpdesk/tree/development/public/"
    click APIClient "https://github.com/faveosuite/faveo-helpdesk/blob/development/routes/api.php"
    click APIClient "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Api/routes.php"
    click Router "https://github.com/faveosuite/faveo-helpdesk/blob/development/routes/web.php"
    click Router "https://github.com/faveosuite/faveo-helpdesk/blob/development/routes/api.php"
    click Middleware "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Http/Middleware/"
    click AdminCtrl "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Http/Controllers/Admin/"
    click AgentCtrl "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Http/Controllers/Agent/"
    click ClientCtrl "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Http/Controllers/Client/"
    click InstallerCtrl "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Http/Controllers/Installer/"
    click UpdateCtrl "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Http/Controllers/Update/"
    click APIV1Ctrl "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Api/v1/*.php"
    click APIV2Ctrl "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Api/v2/*.php"
    click CoreProv "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Providers/AppServiceProvider.php"
    click CoreProv "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Providers/AuthServiceProvider.php"
    click CoreProv "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Providers/EventServiceProvider.php"
    click CoreProv "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Providers/RouteServiceProvider.php"
    click APIProv "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Api/ApiServiceProvider.php"
    click PluginProv "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Plugins/ServiceProvider.php"
    click PluginProv "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/FaveoStorage/StorageServiceProvider.php"
    click PluginProv "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/FaveoLog/LaravelLogViewerServiceProvider.php"
    click Events "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Events/"
    click Listeners "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Listeners/"
    click Scheduler "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Console/Commands/"
    click Scheduler "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Console/Kernel.php"
    click Scheduler "https://github.com/faveosuite/faveo-helpdesk/blob/development/routes/console.php"
    click QueueWorker "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Jobs/SendEmail.php"
    click Models "https://github.com/faveosuite/faveo-helpdesk/tree/development/app/Model/"
    click Migrations "https://github.com/faveosuite/faveo-helpdesk/tree/development/database/migrations/"
    click FileStorage "https://github.com/faveosuite/faveo-helpdesk/tree/development/storage/app/"
    click PublicFiles "https://github.com/faveosuite/faveo-helpdesk/tree/development/public/vendor"
    click Blade "https://github.com/faveosuite/faveo-helpdesk/tree/development/resources/views/"
    click Blade "https://github.com/faveosuite/faveo-helpdesk/tree/development/resources/views/themes/"
    click Assets "https://github.com/faveosuite/faveo-helpdesk/blob/development/webpack.mix.js"
    click SMTP "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Model/MailJob/MailService.php"
    click SMTP "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Model/MailJob/FaveoQueue.php"
    click Bugsnag "https://github.com/faveosuite/faveo-helpdesk/blob/development/config/bugsnag.php"
    click SocialAPIs "https://github.com/faveosuite/faveo-helpdesk/blob/development/app/Http/Controllers/Common/Socialite.php"
    click SocialAPIs "https://github.com/faveosuite/faveo-helpdesk/blob/development/config/services.php"

    %% Styles
    classDef requestflow fill:#E3F2FD,stroke:#42A5F5,color:#0D47A1
    classDef async fill:#E8F5E9,stroke:#66BB6A,color:#1B5E20
    classDef external fill:#FFF3E0,stroke:#FFA726,color:#E65100
```
