# hoceineel/abi-zaid-quran architecture

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

- Interactive diagram: https://gitdiagram.com/hoceineel/abi-zaid-quran
- Repository: https://github.com/hoceineel/abi-zaid-quran

## Overview

##### Project type and purpose
- This is a full-stack monolithic web application (Laravel 11) with an admin dashboard (Filament 3.x), Livewire dynamic components, PWA support and integrations (WhatsApp, PDF reports). It manages Quran memorization schools: students, groups, attendance, progress tracking, communications, and payments.

##### Main components
a. Frontend
- Browser / PWA client
- Tailwind CSS + Livewire components (QR scanner, charts)
- Filament admin panel UI
b. Backend (Laravel MVC)
- HTTP layer: routes → Controllers (web.php, Console commands)
- Models / Eloquent ORM
- Services layer: WhatsAppService, DisconnectionService, ReceiptService
- Jobs / Queue: SendWhatsAppMessageJob
- Console commands (font installer, test connections, scheduled reminders)
c. Database
- MySQL (or SQLite)
- Tables: users, students, groups, attendances, progresses, payments, reminder_logs, whatsapp_sessions, whatsapp_message_histories, etc.
d. External services
- WhatsApp Business API (sending/receiving messages)
- PDF generation (dompdf)
- PWA service worker (caching, offline)
- Storage (local disk / S3 via Laravel Filesystems)

##### Relationships & data flows
- User / Guardian / Teacher (browser) → HTTP request → Laravel router → Controller or Livewire component → Service or Model → Database → Response → UI
- Livewire components (e.g., QR scanner) use WebSockets or AJAX calls to backend actions
- Filament dashboard CRUD → Resource classes → Eloquent Models → DB
- Controller or Job enqueues SendWhatsAppMessageJob → Queue worker → WhatsAppService → External WhatsApp API → Guardian’s phone
- PDF report request → ReceiptService → dompdf → PDF output → Browser download
- PWA client fetches serviceworker.js → caches assets → offline support

##### Architectural patterns & design principles
- MVC separation (Controllers, Models, Views)
- Resource-based admin panel (Filament Resources → Pages → RelationManagers)
- Service layer for business logic (Services folder)
- Asynchronous processing via queue workers (Jobs)
- Single codebase monolith with clear modular subsystems
- PWA enhancements for mobile

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Presentation Layer
    subgraph "Presentation Layer" 
        direction TB
        Browser["Browser / PWA Client"]:::frontend
        SW["Service Worker"]:::frontend
    end

    %% Application Layer
    subgraph "Application Layer"
        direction TB
        subgraph "HTTP Layer"
            direction TB
            Routes["Routes (web.php, console.php)"]:::backend
            Controllers["Controllers"]:::backend
        end
        subgraph "Livewire Module"
            direction TB
            Livewire["Livewire Components"]:::backend
        end
        subgraph "Filament Admin"
            direction TB
            Filament["Filament Resources & UI"]:::backend
        end
        subgraph "Service Layer"
            direction TB
            Services["Business Services"]:::backend
        end
        subgraph "Job Dispatch"
            direction TB
            Dispatcher["Job Dispatcher"]:::backend
        end
    end

    %% Worker
    subgraph "Queue Worker"
        direction TB
        Worker["Worker (Queue)"]:::worker
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB[(MySQL Database)]:::db
        Storage[(Storage / S3)]:::storage
    end

    %% External Services
    subgraph "External Services"
        direction TB
        WhatsAppAPI["WhatsApp Business API"]:::external
        PDFService["PDF Generation (dompdf)"]:::external
    end

    %% Flows
    Browser -->|HTTP Request| Routes
    SW -->|Asset Request & Caching| Browser
    Browser -->|Livewire Call| Livewire
    Routes -->|Call| Controllers
    Controllers -->|Use| Services
    Livewire -->|Call| Services
    Filament -->|CRUD via Resources| Controllers
    Services -->|Query/Update| DB
    Controllers -->|Dispatch| Dispatcher
    Dispatcher -.->|Queue Job| Worker
    Worker -->|API Call| WhatsAppAPI
    Controllers -->|Generate PDF via dompdf| PDFService
    Controllers -->|Store Files| Storage
    Services -->|Store Files| Storage

    DB -->|Read/Write| Controllers
    DB -->|Read/Write| Services

    %% Click events
    click Browser "https://github.com/hoceineel/abi-zaid-quran/blob/master/resources/js/app.js"
    click SW "https://github.com/hoceineel/abi-zaid-quran/blob/master/public/serviceworker.js"
    click Livewire "https://github.com/hoceineel/abi-zaid-quran/blob/master/app/Livewire/QrCodeScanner.php"
    click Filament "https://github.com/hoceineel/abi-zaid-quran/tree/master/app/Filament"
    click Routes "https://github.com/hoceineel/abi-zaid-quran/blob/master/routes/web.php"
    click Controllers "https://github.com/hoceineel/abi-zaid-quran/blob/master/app/Http/Controllers/WhatsAppController.php"
    click Services "https://github.com/hoceineel/abi-zaid-quran/blob/master/app/Services/WhatsAppService.php"
    click Dispatcher "https://github.com/hoceineel/abi-zaid-quran/blob/master/app/Jobs/SendWhatsAppMessageJob.php"
    click DB "https://github.com/hoceineel/abi-zaid-quran/tree/master/database/migrations"
    click PDFService "https://github.com/hoceineel/abi-zaid-quran/blob/master/resources/views/payments/receipt.blade.php"
    click Storage "https://github.com/hoceineel/abi-zaid-quran/tree/master/storage/app"

    %% Styles
    classDef frontend fill:#D0E8FF,stroke:#004EAA,color:#004EAA
    classDef backend fill:#DFFFE0,stroke:#1A7F00,color:#1A7F00
    classDef worker fill:#E0F7FF,stroke:#007F9A,color:#005F7F
    classDef db fill:#CCCCCC,stroke:#666666,color:#333333
    classDef storage fill:#EEEEEE,stroke:#AAAAAA,color:#555555
    classDef external fill:#FFEFD0,stroke:#AA6800,color:#AA4500
```
