How nocturnnn32/insti works
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