How itsx-dual/api_cebv works
Project Type and Purpose
• This is a monolithic Laravel-based backend API whose sole responsibility is to serve as the data-and-document generation layer for a desktop and mobile application used by the Comisión Estatal de Búsqueda del estado de Veracruz to search for missing persons.
• It exposes RESTful endpoints protected by Laravel Sanctum, performs business logic in a Service layer, and generates PDF reports via Blade templates and DomPDF.
File Structure Analysis
• Top-level folders:
• app/ (Controllers, Models, Services, Observers, Helpers, Exports) – the MVC + service layer + domain logic
• config/, bootstrap/, public/ – framework config, front-controller and asset storage
• database/ (migrations, seeders, factories) – schema and seed data
• resources/ (views, CSS, JS) – Blade layouts and assets for PDF report templates
• routes/ (api.php, web.php, reportes.php) – endpoint definitions
• docker-compose.yml – container definitions for PHP/FPM, web server, DB, etc.
• Architectural patterns:
• MVC: Controllers → Models → Resources
• Service Layer: app/Services handles complex CRUD and report generation
• Observer/Event: app/Observers for side-effects on Eloquent events
• Request Objects: app/Http/Requests encapsulate validation
To accurately represent this architecture, break it into the following main components:
A. Clients (External Actors)
• Desktop App (e.g., Electron, .NET)
• Mobile App (iOS/Android)
• Operator’s browser (for testing via Postman or Xhttp scripts)
– These issue HTTPS requests with Bearer tokens.
B. API Gateway & Edge Services
• Reverse Proxy / Load Balancer (nginx or Traefik within Docker Compose)
• SSL termination and CORS middleware (config/cors.php)
C. Laravel Application Container
1. HTTP Kernel & Middleware
– Authenticate (Sanctum), CSRF, CORS, JSON responses
2. Routing Layer
– routes/api.php for core API
– routes/reportes.php for PDF generation endpoints
3. Controllers (app/Http/Controllers)
– Receive validated requests (via app/Http/Requests)
– Invoke Services or Eloquent operations
4. Service Layer (app/Services)
– CrudService: generic CRUD logic
– ReporteService: orchestrates data gathering + PDF generation
– SyncPersonaService: handles background sync tasks
5. Domain Models & Persistence
– Eloquent Models (app/Models) map to MySQL tables
– Observers handle side effects (e.g., DesaparecidoObserver)
6. Resources & Transformations
– app/Http/Resources format JSON payloads
7. Blade Templates & DomPDF
– resources/views + DomPDF service for document rendering
8. Caching & Queues (optional extensions)
– config/cache.php, config/queue.php – could plug Redis or database driver
9. Logging & Monitoring
– Monolog via config/logging.php
D. Data Storage
• MySQL (or MariaDB) container – persistent volume for database
• Storage directory (files, fonts, generated PDFs)
Relationships and Data Flow
1. Client → HTTPS → Reverse Proxy (Docker nginx)
2. Proxy → Laravel HTTP Kernel
3. Kernel → Route matching & Middleware → Controller
4. Controller → Request Validator → Service or direct Model
5. Service → Eloquent ORM → MySQL
6. MySQL → Eloquent Model → Service → Controller
7. Controller → JSON Resource or Blade+DomPDF → HTTP Response → Client
8. Observers & Events fire asynchronously on model lifecycle
9. Optionally, queued jobs for heavy tasks (e.g., bulk seed, synchronization)
Key Architectural Patterns
• MVC for request handling and response generation
• Service Layer to keep Controllers thin and reusable
• Observers for domain events (e.g., reindexing, logging)
• Request/Resource objects to enforce separation of concerns
• Docker Compose for reproducible environment (PHP-FPM, DB, nginx)
Technologies & Frameworks to Call Out
• PHP 8.3, Laravel 10.x
• Laravel Sanctum (API token management)
• Eloquent ORM & Migrations/Seeders/Factories
• DomPDF + Blade for PDF reports
• Docker, Docker Compose, Laravel Sail
• MySQL (or MariaDB)
• Optional: Redis for cache/queue