# itsx-dual/api_cebv architecture

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

- Interactive diagram: https://gitdiagram.com/itsx-dual/api_cebv
- Repository: https://github.com/itsx-dual/api_cebv

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        direction TB
        DesktopApp["Desktop App"]:::external
        MobileApp["Mobile App"]:::external
        Browser["Operator Browser"]:::external
    end

    %% Edge / API Gateway
    subgraph "API Gateway & Edge Services"
        direction TB
        Proxy["Reverse Proxy / Load Balancer\n(nginx/Traefik)"]:::app
        CORSConfig["CORS Middleware\n(config/cors.php)"]:::app
    end

    %% Laravel Application Container
    subgraph "Laravel App Container"
        direction TB

        subgraph "HTTP Kernel & Middleware"
            direction TB
            Kernel["HTTP Kernel\n(app/Http/Kernel.php)"]:::app
            Middleware["Middleware\n(app/Http/Middleware/)"]:::app
        end

        subgraph "Routing Layer"
            direction TB
            APIRoutes["API Routes\n(routes/api.php)"]:::app
            ReportRoutes["Report Routes\n(routes/reportes.php)"]:::app
            WebRoutes["Web Routes\n(routes/web.php)"]:::app
        end

        subgraph "Controller Layer"
            direction TB
            Controllers["Controllers\n(app/Http/Controllers/)"]:::app
            Requests["Request Objects\n(app/Http/Requests/)"]:::app
        end

        subgraph "Service Layer"
            direction TB
            CrudService["CrudService\n(app/Services/CrudService.php)"]:::app
            ReporteService["ReporteService\n(app/Services/ReporteService.php)"]:::app
            SyncPersonaService["SyncPersonaService\n(app/Services/SyncPersonaService.php)"]:::app
        end

        subgraph "Domain Models & Persistence"
            direction TB
            Models["Eloquent Models\n(app/Models/)"]:::app
            Observers["Observers\n(app/Observers/)"]:::app
        end

        subgraph "Presentation & Reporting"
            direction TB
            Resources["JSON Resources\n(app/Http/Resources/)"]:::app
            BladeViews["Blade Templates\n(resources/views/)"]:::app
            DomPDFConfig["DomPDF Config\n(config/dompdf.php)"]:::app
        end

        subgraph "Config & Extensions"
            direction TB
            CacheConfig["Cache Config\n(config/cache.php)"]:::app
            QueueConfig["Queue Config\n(config/queue.php)"]:::app
            SanctumConfig["Sanctum Auth\n(config/sanctum.php)"]:::app
            LoggingConfig["Logging Config\n(config/logging.php)"]:::app
        end
    end

    %% Data Stores & Assets
    subgraph "Data Storage & Assets"
        direction TB
        DB["MySQL Database"]:::datastore
        Storage["Storage Volume\n(storage/)"]:::datastore
        PublicIndex["Front Controller\n(public/index.php)"]:::datastore
        PublicAssets["Static Assets\n(public/css/, public/fonts/)"]:::datastore
        PDFExamples["Generated PDFs\n(public/reportes/)"]:::datastore
    end

    %% Flows
    DesktopApp -->|HTTPS| Proxy
    MobileApp -->|HTTPS| Proxy
    Browser -->|HTTPS| Proxy

    Proxy -->|HTTPS| Kernel
    Proxy --> CORSConfig
    CORSConfig --> Kernel

    Kernel -->|route| APIRoutes
    Kernel -->|route| ReportRoutes
    Kernel -->|route| WebRoutes

    APIRoutes --> Controllers
    ReportRoutes --> Controllers
    WebRoutes --> Controllers

    Controllers --> Requests
    Controllers -->|invoke| CrudService
    Controllers -->|invoke| ReporteService
    Controllers -->|invoke| SyncPersonaService

    CrudService --> Models
    ReporteService --> Models
    SyncPersonaService --> Models

    Models -->|SQL| DB
    DB -->|result| Models

    Models --> Observers
    Observers -.->|events| Models

    Controllers --> Resources
    Controllers --> BladeViews
    BladeViews --> DomPDFConfig

    Resources -->|JSON| Proxy
    DomPDFConfig -->|PDF| Proxy

    %% Click Events
    click Proxy "https://github.com/itsx-dual/api_cebv/blob/main/docker-compose.yml"
    click CORSConfig "https://github.com/itsx-dual/api_cebv/blob/main/config/cors.php"
    click Kernel "https://github.com/itsx-dual/api_cebv/blob/main/app/Http/Kernel.php"
    click Middleware "https://github.com/itsx-dual/api_cebv/tree/main/app/Http/Middleware/"
    click APIRoutes "https://github.com/itsx-dual/api_cebv/blob/main/routes/api.php"
    click ReportRoutes "https://github.com/itsx-dual/api_cebv/blob/main/routes/reportes.php"
    click WebRoutes "https://github.com/itsx-dual/api_cebv/blob/main/routes/web.php"
    click Controllers "https://github.com/itsx-dual/api_cebv/tree/main/app/Http/Controllers/"
    click Requests "https://github.com/itsx-dual/api_cebv/tree/main/app/Http/Requests/"
    click CrudService "https://github.com/itsx-dual/api_cebv/blob/main/app/Services/CrudService.php"
    click ReporteService "https://github.com/itsx-dual/api_cebv/blob/main/app/Services/ReporteService.php"
    click SyncPersonaService "https://github.com/itsx-dual/api_cebv/blob/main/app/Services/SyncPersonaService.php"
    click Models "https://github.com/itsx-dual/api_cebv/tree/main/app/Models/"
    click Observers "https://github.com/itsx-dual/api_cebv/tree/main/app/Observers/"
    click Resources "https://github.com/itsx-dual/api_cebv/tree/main/app/Http/Resources/"
    click BladeViews "https://github.com/itsx-dual/api_cebv/tree/main/resources/views/"
    click DomPDFConfig "https://github.com/itsx-dual/api_cebv/blob/main/config/dompdf.php"
    click CacheConfig "https://github.com/itsx-dual/api_cebv/blob/main/config/cache.php"
    click QueueConfig "https://github.com/itsx-dual/api_cebv/blob/main/config/queue.php"
    click SanctumConfig "https://github.com/itsx-dual/api_cebv/blob/main/config/sanctum.php"
    click LoggingConfig "https://github.com/itsx-dual/api_cebv/blob/main/config/logging.php"
    click DB "https://github.com/itsx-dual/api_cebv/tree/main/database/migrations/"
    click DB "https://github.com/itsx-dual/api_cebv/tree/main/database/seeders/"
    click DB "https://github.com/itsx-dual/api_cebv/tree/main/database/factories/"
    click Storage "https://github.com/itsx-dual/api_cebv/tree/main/storage/"
    click PublicIndex "https://github.com/itsx-dual/api_cebv/blob/main/public/index.php"
    click PublicAssets "https://github.com/itsx-dual/api_cebv/tree/main/public/css/"
    click PublicAssets "https://github.com/itsx-dual/api_cebv/tree/main/public/fonts/"
    click PDFExamples "https://github.com/itsx-dual/api_cebv/tree/main/public/reportes/"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef app fill:#90EE90,stroke:#333,stroke-width:1px
    classDef datastore fill:#FFA500,stroke:#333,stroke-width:1px
```
