# nocturnnn32/insti architecture

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

- Interactive diagram: https://gitdiagram.com/nocturnnn32/insti
- Repository: https://github.com/nocturnnn32/insti

## Overview

##### Project Type and Purpose
- This is a monolithic, full-stack Laravel (PHP) web application for automating enrollment and grade management in a school (“Colegio Manto de Gracias”).
- It follows the MVC pattern, includes Blade views, Livewire components, React/JSX report widgets, Excel and PDF export, user authentication, roles & permissions, and uses a relational database.

##### File Structure and Technical Stack
- Top-level:
- “app/” (Controllers, Models, Requests, Resources, Policies, Exports, Imports, Livewire).
- “resources/” (Blade views, React components, CSS/SASS, JS).
- “routes/” (web.php, api.php, console.php, channels.php).
- “config/” (database, cache, queue, livewire, dompdf, excel).
- “database/” (migrations, factories, seeders).
- “public/” (entry point index.php, assets).
- “bootstrap/” (app initialization).
- “storage/” (logs, sessions, cache, file uploads).
- Key frameworks/libs:
- Laravel core (Routing, Eloquent ORM, Service Providers, Middleware).
- Livewire (for reactive UI).
- React (for specialized report components).
- Maatwebsite Excel & Dompdf (for exports).
- Spatie Roles & Permissions.
- Laravel Sanctum (personal access tokens).
- Laravel Queue, Cache, Broadcasting.
- Webpack Mix (asset compilation).

##### Main Architectural Components
A. Client Browser (UI)
- Blade templates rendered on server
- Livewire components for interactivity
- React/JSX widgets for report charts
- CSS/JS assets via webpack.mix.js
B. Web Server & PHP Runtime
- Nginx/Apache → index.php → Laravel Kernel
- Middleware layer (auth, CSRF, trimming, etc.)
- HTTP Controllers & Livewire controllers
- Form Requests (validation) & Resource Transformers
- Policies (authorization)
C. Business & Domain Layer
- Eloquent Models (Estudiante, Matricula, Calificaciones, etc.)
- Services: Exportables (ExcelReporte…), PDF generators
- Console Commands (app/Console)
- Event Listeners & Broadcasting
D. Data Layer
- MySQL/MariaDB (configured in config/database.php)
- Migrations, Factories, Seeders (to structure & seed data)
- Cache store (Redis or file)
- Queue driver (Redis or database)
- Storage disks (local or S3)
E. External Services
- SMTP mail (password resets, notifications)
- Third-party storage or CDN (optional)
- Task queue workers, broadcast servers

##### Relationships & Data Flow
1. User in browser sends HTTP request → Web Server
2. Web Server hands off to PHP-FPM → Laravel Kernel
3. Middleware processes request → routes/web.php or api.php
4. Controller or Livewire component handles logic → uses FormRequest validation → interacts with Eloquent Models
5. Models perform CRUD on Database; may enqueue jobs or cache data
6. Controller returns Blade view or JSON response
7. Browser receives rendered HTML/JS/CSS or JSON for SPA widgets
8. For exports: Controller calls Excel or PDF service → generates file → stored on disk or streamed back
9. Queue workers process background jobs (emails, exports) asynchronously
10. Authorization via Policies & Roles occur at controller or model level

##### Architectural Patterns & Design Principles
- MVC (separation of concerns)
- PSR-4 autoloading, Service Container, Dependency Injection
- Layered architecture: HTTP layer, Domain layer, Data layer
- Single responsibility (FormRequests, Resources, Policies)
- Event-driven & queued tasks for heavy work
- Reactive components (Livewire) for real-time UI updates
- Modular exports/imports for extensibility

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% UI Layer
    subgraph "UI Layer"
        direction TB
        Browser["Client Browser"]:::ui
        Blade["Blade Templates"]:::ui
        LivewireComponents["Livewire Components"]:::ui
        ReactWidgets["React Report Widgets"]:::ui
        CSS["App CSS"]:::ui
        JS["App JS"]:::ui
        Mix["Webpack Mix"]:::ui
    end

    %% Web Server & PHP Runtime
    subgraph "Web Server & PHP Runtime"
        direction TB
        Nginx["Nginx/Apache"]:::server
        PHPFPM["PHP-FPM"]:::server
        Kernel["Laravel Kernel"]:::server
        Middleware["Middleware & Routing"]:::server
    end

    %% Application & Domain Layer
    subgraph "Application & Domain Layer"
        direction TB
        Controllers["HTTP & Livewire Controllers"]:::app
        FormRequests["Form Requests & Validation"]:::app
        Resources["Resource Transformers"]:::app
        Policies["Authorization Policies"]:::domain
        Models["Eloquent Models"]:::domain
        ExportServices["Excel & PDF Services"]:::app
        ConsoleCmds["Console Commands"]:::app
    end

    %% Data Layer
    subgraph "Data Layer"
        direction TB
        DB["MySQL/MariaDB"]:::data
        Migrations["Migrations / Seeders / Factories"]:::data
        Cache["Cache Store"]:::data
        Queue["Queue Driver"]:::data
        Storage["Storage Disks & Logs"]:::data
    end

    %% External Services
    subgraph "External Services"
        direction TB
        SMTP["SMTP Mail"]:::external
        CDN["Third-party Storage/CDN"]:::external
        Broadcast["Broadcast Server"]:::external
    end

    %% Relationships
    Browser -->|HTTP Request| Nginx
    Nginx --> PHPFPM
    PHPFPM --> Kernel
    Kernel --> Middleware
    Middleware --> Controllers
    Controllers -->|uses| FormRequests
    Controllers -->|transforms| Resources
    Controllers -->|calls| Policies
    Controllers -->|CRUD| Models
    Models --> DB
    Models --> Cache
    Models --> Queue
    Controllers -->|export| ExportServices
    ExportServices --> Storage
    Kernel --> Cache
    Kernel --> Queue
    Queue -->|processed by| ConsoleCmds
    ConsoleCmds --> DB
    Kernel --> SMTP
    Kernel --> Broadcast

    %% Click Events
    click Blade "https://github.com/nocturnnn32/insti/tree/master/resources/views/"
    click LivewireComponents "https://github.com/nocturnnn32/insti/tree/master/app/Http/Livewire/"
    click ReactWidgets "https://github.com/nocturnnn32/insti/tree/master/resources/js/components/reportes/"
    click CSS "https://github.com/nocturnnn32/insti/blob/master/resources/css/app.css"
    click JS "https://github.com/nocturnnn32/insti/blob/master/resources/js/app.js"
    click Mix "https://github.com/nocturnnn32/insti/blob/master/webpack.mix.js"
    click Nginx "https://github.com/nocturnnn32/insti/blob/master/public/index.php"
    click Kernel "https://github.com/nocturnnn32/insti/blob/master/app/Http/Kernel.php"
    click Middleware "https://github.com/nocturnnn32/insti/tree/master/app/Http/Middleware/"
    click Controllers "https://github.com/nocturnnn32/insti/tree/master/app/Http/Controllers/"
    click FormRequests "https://github.com/nocturnnn32/insti/tree/master/app/Http/Requests/"
    click Resources "https://github.com/nocturnnn32/insti/tree/master/app/Http/Resources/"
    click ExportServices "https://github.com/nocturnnn32/insti/blob/master/app/Exports/CalificacionesExport.php"
    click ConsoleCmds "https://github.com/nocturnnn32/insti/tree/master/app/Console/"
    click Models "https://github.com/nocturnnn32/insti/tree/master/app/Models/"
    click Policies "https://github.com/nocturnnn32/insti/tree/master/app/Policies/"
    click DB "https://github.com/nocturnnn32/insti/blob/master/config/database.php"
    click Cache "https://github.com/nocturnnn32/insti/blob/master/config/cache.php"
    click Queue "https://github.com/nocturnnn32/insti/blob/master/config/queue.php"
    click Storage "https://github.com/nocturnnn32/insti/tree/master/storage/framework/"
    click Migrations "https://github.com/nocturnnn32/insti/tree/master/database/migrations/"
    click SMTP "https://github.com/nocturnnn32/insti/blob/master/config/mail.php"
    click CDN "https://github.com/nocturnnn32/insti/blob/master/config/filesystems.php"
    click Broadcast "https://github.com/nocturnnn32/insti/blob/master/config/broadcasting.php"

    %% Styles
    classDef ui fill:#88ccff,stroke:#333,stroke-width:1px
    classDef server fill:#aaffaa,stroke:#333,stroke-width:1px
    classDef app fill:#ccff99,stroke:#333,stroke-width:1px
    classDef domain fill:#99ee99,stroke:#333,stroke-width:1px
    classDef data fill:#ffcc66,stroke:#333,stroke-width:1px
    classDef external fill:#dddddd,stroke:#333,stroke-width:1px
```
