# ayoubettalbi/tikoschool architecture

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

- Interactive diagram: https://gitdiagram.com/ayoubettalbi/tikoschool
- Repository: https://github.com/ayoubettalbi/tikoschool

## Overview

##### Project Type and Purpose
- This is a full-stack web application built on the Laravel PHP framework, serving as a school management platform (managing schools, classes, students, teachers, attendance, invoices, messaging, etc.).
- The front end is a single-page application (SPA) using React (JSX files in resources/js) integrated via Inertia.js and bundled with Vite.
- It leverages Laravel’s MVC, Eloquent ORM, event-broadcasting (Laravel Echo), queues, and policy-based authorization.

##### File Structure Analysis
- app/
- Controllers (HTTP endpoints)
- Models (Eloquent entities)
- Events & Listeners (event-driven updates for chat, notifications, read receipts)
- Policies (authorization checks)
- Requests (validation rules)
- routes/ (web.php, auth.php): HTTP routes and channel definitions.
- resources/js/: React components, layouts, pages, forms—entry point at app.jsx and bootstrap.js.
- resources/views/: Blade templates for server-rendered invoice PDFs.
- config/: DB, cache, queue, broadcasting (Pusher or WebSockets), mail, filesystems configs.
- database/: migrations and seeders defining tables for users, schools, classes, messages, invoices, etc.
- public/: index.php bootstraps Laravel and serves the SPA.
- storage/: uploaded files, cache, logs, sessions.
- queue/workers: Artisan queue workers process background jobs (emails, PDFs, analytics).

##### Key Architectural Patterns & Components
- MVC on the server: HTTP Kernel → Middleware → Controllers → Services/Models → Database.
- Eloquent ORM for data access; MySQL or PostgreSQL as primary RDBMS.
- Event-driven flows for real-time features (chat, notifications) via Laravel Events → Broadcast → Echo/Pusher/WebSockets.
- Job Queues for asynchronous tasks (email notifications, PDF generation, scheduled promotions).
- Inertia.js bridging React SPA with Laravel routes for seamless page transitions.
- Policies and Gates for role-based access control (Admin, Teacher, Assistant, Student).
- Vite for modern asset bundling (JSX, CSS, Tailwind).

##### Main System Components
a. Client (Browser)
- React SPA (Inertia.js)
- HTTP calls (axios/fetch)
- WebSocket/Echo subscription
b. Laravel Backend
- HTTP Kernel & Middleware
- Controllers & Request Validation
- Event Dispatcher & Listeners
- Job Queue & Workers
- Service Providers & Dependency Injection
- Blade for PDF rendering
c. Persistence & Caching
- Relational Database (MySQL/PostgreSQL)
- Cache store (Redis or file cache)
- Filesystem Storage (local or S3 for private/public uploads)
d. Real-Time & Asynchronous Services
- Broadcasting (Pusher or Laravel WebSockets)
- Queue driver (Redis or database)
- Mail service (SMTP, SES, Mailgun)
e. External Integrations
- Payment gateway (if Offers/Invoices integrate externally)
- Analytics or third-party APIs (config/services.php)

##### Relationships and Data Flows
- Client → HTTP (GET/POST/PUT/DELETE) → Laravel Routes → Controllers → Eloquent → Database
- Controllers → dispatch Events → Event Listeners → Broadcast via WebSocket → Client
- Controllers or Events → dispatch Jobs → Queue → Worker processes → external API or DB
- Client establishes WebSocket connection to Broadcasting server for real-time updates
- Files uploaded by Client → Laravel Storage → local disk or S3; file metadata in DB
- Scheduled tasks (artisan schedule) → regularly run promotions, cleanup, notifications

##### Essential Details Not to Omit
- Authentication & Policy checks in Middleware/Controllers.
- Validation layer (FormRequests).
- Event broadcasting flow for chat and unread counters.
- Queue and Worker separation for background processing.
- Asset pipeline (Vite) and entrypoint (resources/js/app.jsx → public/js).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Client (Browser)"
        SPA["React SPA (Inertia.js)"]:::frontend
        HTTP["HTTP/JSON Calls"]:::frontend
        WS["WebSocket/Echo"]:::frontend
    end

    subgraph "Backend (Laravel App)"
        HK["HTTP Kernel & Middleware"]:::backend
        SP["Service Providers & DI"]:::backend
        CT["Controllers"]:::backend
        RV["FormRequests (Validation)"]:::backend
        ED["Event Dispatcher & Listeners"]:::backend
        JQ["Job Queue"]:::backend
        WK["Queue Workers"]:::backend
        BP["Blade PDF Rendering"]:::backend
    end

    subgraph "Data Stores"
        DB[(MySQL/PostgreSQL)]:::datastore
        CA[(Redis Cache)]:::datastore
        FS[(File Storage: local/S3)]:::datastore
    end

    subgraph "External Services"
        WSvr["Pusher/WebSocket Server"]:::external
        Mail["Mail Service (SMTP/SES/Mailgun)"]:::external
        Pay["Payment Gateway"]:::external
        Anl["Analytics API"]:::external
    end

    SPA -->|HTTP/JSON| HK
    HK -->|invoke| SP
    HK -->|route| CT
    CT -->|authorize| RV
    CT -->|dispatch Event| ED
    CT -->|dispatch Job| JQ
    ED -->|broadcast| WSvr
    WSvr -->|WebSocket| SPA
    JQ -->|process| WK
    WK -->|send email| Mail
    WK -->|external payment| Pay
    WK -->|analytics| Anl
    CT -->|read/write| DB
    CT -->|cache| CA
    CT -->|upload/download| FS
    BP -->|render to file| FS
    BP -->|record metadata| DB

    click SPA "https://github.com/ayoubettalbi/tikoschool/blob/ayoub/resources/js/app.jsx"
    click HK "https://github.com/ayoubettalbi/tikoschool/blob/ayoub/app/Http/Kernel.php"
    click SP "https://github.com/ayoubettalbi/tikoschool/tree/ayoub/app/Providers/"
    click CT "https://github.com/ayoubettalbi/tikoschool/tree/ayoub/app/Http/Controllers/"
    click RV "https://github.com/ayoubettalbi/tikoschool/tree/ayoub/app/Http/Requests/"
    click ED "https://github.com/ayoubettalbi/tikoschool/tree/ayoub/app/Events/"
    click JQ "https://github.com/ayoubettalbi/tikoschool/blob/ayoub/config/queue.php"
    click BP "https://github.com/ayoubettalbi/tikoschool/tree/ayoub/resources/views/invoices/"
    click CA "https://github.com/ayoubettalbi/tikoschool/blob/ayoub/config/cache.php"
    click FS "https://github.com/ayoubettalbi/tikoschool/blob/ayoub/config/filesystems.php"

    classDef frontend fill:#D0E8FF,stroke:#000;
    classDef backend fill:#D0FFD6,stroke:#000;
    classDef datastore fill:#FFE0A3,stroke:#000;
    classDef external fill:#E0E0E0,stroke:#000;
```
