# rathfaisal/pebs architecture

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

- Interactive diagram: https://gitdiagram.com/rathfaisal/pebs
- Repository: https://github.com/rathfaisal/pebs

## Overview

##### Project type and purpose
- This is a full-stack, monolithic web application built on Laravel 12 (PHP 8.2+) with Blade templates, Bootstrap/Tailwind CSS, and Vite for asset bundling.
- Its purpose is to serve as the PeBS Management System with three role-based dashboards (Super Admin, Admin, User) for activity and user management.

##### File structure
- Top-level directories:
- app/ – contains MVC core (Controllers, Models, Middleware, Service Providers, View Components)
- config/ – environment and service configuration (database, cache, mail, queue, session)
- database/ – migration and seeder definitions for users, activities, pivot tables
- resources/ – Blade view templates (layouts, components, role-specific views), CSS/JS assets
- public/ – web-server document root (index.php entry point, compiled assets, images)
- routes/ – HTTP and console routing (web.php, auth.php)
- Deployment files: .env, artisan CLI, composer.json, vite.config.js.

##### README for additional insights
- The README provides:
- An overview of user roles and feature sets
- Technology stack: Laravel Breeze for auth, MySQL/MariaDB, PHPUnit tests.

a. Main components
- Clients (Web Browser/Mobile Web)
- Web Server (Nginx/Apache + PHP-FPM)
- Laravel Application (MVC layers)
- Data Stores: MySQL/MariaDB, File Storage (local S3-compatible), Cache/Queue (Redis or file)
- External Services: Mail (SMTP/SendGrid), Optional CDN for assets
b. Relationships & interactions
- Clients send HTTP(S) requests → Web Server → PHP-FPM → Laravel Router → Controllers →
- Models (Eloquent ORM) ↔ MySQL
- File I/O for pictures, uploads
- Queue jobs (email notifications, activity restore)
- Controllers return Blade views or JSON responses
- Assets: Vite dev server in development, compiled CSS/JS in production served by public/
- Middleware enforces RBAC before entering controllers
c. Architectural patterns / design principles
- MVC: clear separation of Views (resources/views), Controllers (app/Http/Controllers), Models (app/Models)
- Service Providers for DI and bootstrapping
- Middleware for authentication and role checks (IsAdmin, IsSuperAdmin)
- Database Migrations & Seeders for schema management
- RESTful resource controllers for CRUD on activities, announcements, admins
d. Key technologies
- PHP 8.2, Laravel 12.x, Laravel Breeze (auth scaffolding)
- Blade templating, Bootstrap 5, Tailwind CSS
- Vite & npm for asset bundling
- MySQL/MariaDB, PHPUnit for tests

##### Detailed capture of architectural elements
- Routes/web.php feeding into the Router → Controllers.
- Middleware (auth, IsAdmin, IsSuperAdmin).
- Background processes: queue dispatcher for sending emails, restoring deleted activities.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Browser["Web/Mobile Browser"]:::frontend
        PublicAssets["Compiled CSS/JS & Images (public/)"]:::frontend
        Browser -->|HTTP/S| WebServer
        Browser -->|Assets| PublicAssets
    end

    %% Web Server
    WebServer["Nginx/Apache + PHP-FPM"]:::app

    %% Application Layer
    subgraph "Laravel Application" 
        direction TB
        Routes["routes/web.php"]:::app
        AuthRoutes["routes/auth.php"]:::app
        Router["Laravel Router"]:::app
        Middleware["Middleware (Auth, IsAdmin, IsSuperAdmin)"]:::app
        Controllers["Controllers"]:::app
        Models["Eloquent Models"]:::app
        Providers["Service Providers"]:::app
        ViewComponents["Blade View Components"]:::app
        BladeTemplates["Blade Templates"]:::app
        Queue["Queue & Workers"]:::app
        Routes --> Router
        AuthRoutes --> Router
        Router --> Middleware
        Middleware --> Controllers
        Controllers --> Models
        Controllers -->|renders| BladeTemplates
        Controllers -->|uses| ViewComponents
        Controllers --> Queue
        Providers --> Controllers
    end

    %% Data & Storage Layer
    subgraph "Data & Storage" 
        direction TB
        MySQL["MySQL/MariaDB"]:::data
        FileStorage["File Storage (local/S3)"]:::data
        Cache["Redis/File Cache & Queue"]:::data
        QueueDispatcher["Queue Dispatcher"]:::data
        Models --> MySQL
        Controllers --> FileStorage
        Queue --> QueueDispatcher
        QueueDispatcher -->|jobs| Controllers
        Queue --> Cache
    end

    %% External Services
    subgraph "External Services" 
        direction TB
        SMTP["SMTP/SendGrid"]:::external
        CDN["Optional CDN"]:::external
        QueueDispatcher --> SMTP
        PublicAssets --> CDN
    end

    WebServer --> LaravelApp["Laravel Application"]
    LaravelApp --> MySQL
    LaravelApp --> FileStorage

    %% Click Events
    click Controllers "https://github.com/rathfaisal/pebs/tree/main/app/Http/Controllers"
    click Models "https://github.com/rathfaisal/pebs/tree/main/app/Models"
    click Middleware "https://github.com/rathfaisal/pebs/tree/main/app/Http/Middleware"
    click Providers "https://github.com/rathfaisal/pebs/blob/main/app/Providers/AppServiceProvider.php"
    click ViewComponents "https://github.com/rathfaisal/pebs/tree/main/app/View/Components"
    click BladeTemplates "https://github.com/rathfaisal/pebs/tree/main/resources/views"
    click Routes "https://github.com/rathfaisal/pebs/blob/main/routes/web.php"
    click AuthRoutes "https://github.com/rathfaisal/pebs/blob/main/routes/auth.php"
    click MySQL "https://github.com/rathfaisal/pebs/blob/main/config/database.php"
    click FileStorage "https://github.com/rathfaisal/pebs/blob/main/config/filesystem.php"
    click Cache "https://github.com/rathfaisal/pebs/blob/main/config/cache.php"
    click QueueDispatcher "https://github.com/rathfaisal/pebs/blob/main/config/queue.php"
    click PublicAssets "https://github.com/rathfaisal/pebs/tree/main/public"
    click WebServer "https://github.com/rathfaisal/pebs/blob/main/public/index.php"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#333,stroke-width:1px
    classDef app fill:#D0F5D0,stroke:#333,stroke-width:1px
    classDef data fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef external fill:#E0E0E0,stroke:#333,stroke-width:1px
```
