# asistente-informatica-enec/sigb architecture

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

- Interactive diagram: https://gitdiagram.com/asistente-informatica-enec/sigb
- Repository: https://github.com/asistente-informatica-enec/sigb

## Overview

##### Project type and purpose
- This is a full‐stack web application built on Laravel (PHP) with a Filament admin panel and Blade/Vue‐style frontend views.
- Purpose: Manage academic library resources (catalogs, loans, returns, history, reports) and perform an asynchronous cross‐repository search (Project Gutenberg, PMC, PubMed) with on‐the‐fly translation via LibreTranslate.

##### File‐structure analysis
- Top‐level folders
- app/                     ← core application (Console commands, HTTP controllers, models, services, events, jobs, Filament resources/widgets)
- config/, bootstrap/, routes/  ← framework/configuration
- database/                ← migrations, factories, seeders
- public/                  ← web‐accessible assets (CSS/JS for Filament admin & custom search UI)
- resources/               ← Blade views (search pages, Filament pages/widgets, PDFs), frontend assets (JS, CSS)
- storage/                 ← logs, cache, uploaded/generated files
- scripts at root (start‐services.sh, start‐search‐worker.sh) + supervisor‐queue‐worker.conf → deployment/worker orchestration
- Architectural patterns
- MVC in app/Http (Controllers → Models → Views in resources/views)
- Service layer in app/Services for external‐API handling and translation
- Command/Job/Queue pattern (app/Console commands launch background jobs, app/Jobs process API searches)
- Event‐driven updates (app/Events/SearchResultsUpdated, broadcasting via Echo)
- Filament resource pattern (app/Filament/Resources, Widgets, Pages) for admin UI

##### Key README insights
- Emphasis on multilingual meta‐search using three external APIs and LibreTranslate
- Dual UIs: public search interface + Filament admin panel
- Reports in PDF generated under resources/views/pdf and output to storage

a. Main components
- Client browsers
– Public Search UI (Blade views + JS)
– Filament Admin UI (JS/CSS loaded from public/)
- Laravel backend
– HTTP layer: routes/web.php & routes/api.php → Controllers
– Service layer: ExternalApiService, TranslationService
– Data layer: Eloquent Models → MySQL/PostgreSQL
- Queue subsystem
– job dispatcher (SearchExternalApisJob)
– queue backend (Redis/DB as per config/queue.php)
– queue worker (supervisor‐managed, start‐search‐worker.sh)
- Event/Broadcasting
– Events (SearchResultsUpdated)
– WebSocket channel (Echo.js) → real‐time updates in UI
- External systems
– Project Gutenberg API
– PMC API
– PubMed API
– LibreTranslate API
- Storage & artifacts
– File storage for PDFs (Loan/Report outputs)
– Logs & cache

b. Relationships and data flow
1. User triggers search from public UI → HTTP POST to PublicSearchController
2. Controller enqueues SearchExternalApisJob → stored in queue driver
3. Queue worker fetches job → ExternalApiService calls each external API
4. Raw results → TranslationService (via LibreTranslate) → normalized results
5. Event SearchResultsUpdated fired → broadcast to client via WebSocket
6. Browser listens (Echo.js) → renders results asynchronously
7. Admin UI (Filament) interacts with Controllers → CRUD on Books, Authors, Loans → DB
8. Reports: user/admin triggers PDF generation → Controller/Service renders Blade PDF view → stored or streamed

c. Architectural patterns & principles
- MVC separation between UI (Blade/Filament), business logic (Controllers/Services), persistence (Models/DB)
- Event‐driven async updates for search results
- queued background processing for long‐running API calls
- dependency inversion: controllers depend on service‐layer interfaces
- resource‐centric admin UI via Filament

d. Key technologies
- Laravel (PHP 8.x), Eloquent ORM
- Filament (Laravel admin panel)
- Blade templating, Alpine.js/Echo.js for real‐time
- Queues: Redis or database driver, supervisor
- External HTTP APIs + Guzzle (likely)
- LibreTranslate for machine translation
- MySQL/PostgreSQL
- PDF generation (e.g., Dompdf or Snappy)

## Diagram (Mermaid)

```mermaid
graph TB
    %% Client Layer
    subgraph "Client Layer"
        direction TB
        PublicSearchUI["Public Search UI"]:::ui
        FilamentAdminUI["Filament Admin UI"]:::ui
    end

    %% Laravel Application
    subgraph "Laravel App"
        direction TB

        subgraph "HTTP Layer" 
            direction TB
            RoutesWeb["routes/web.php"]:::backend
            RoutesAPI["routes/api.php"]:::backend
            PublicSearchController["PublicSearchController"]:::backend
            BaseController["Controller.php"]:::backend
        end

        subgraph "Service Layer"
            direction TB
            ExternalApiService["ExternalApiService.php"]:::service
            TranslationService["TranslationService.php"]:::service
        end

        subgraph "Data Layer"
            direction TB
            EloquentModels["Eloquent Models"]:::data
            Migrations["Migrations"]:::data
        end

        subgraph "Event & Broadcasting"
            direction TB
            SearchResultsUpdated["SearchResultsUpdated.php"]:::service
            BroadcastProvider["BroadcastServiceProvider.php"]:::service
            ConfigBroadcasting["config/broadcasting.php"]:::backend
        end

        subgraph "Console & Orchestration"
            direction TB
            ProcessSearchQueue["ProcessSearchQueue.php"]:::backend
            StartServicesCmd["StartServices.php"]:::backend
            TestAsyncSearchCmd["TestAsyncSearch.php"]:::backend
            TestLibreTranslateCmd["TestLibreTranslate.php"]:::backend
            ConsoleKernel["Kernel.php"]:::backend
        end
    end

    %% Queue Worker
    subgraph "Queue Worker"
        direction TB
        SearchJob["SearchExternalApisJob.php"]:::queue
        ConfigQueue["config/queue.php"]:::backend
        StartSearchWorker["start-search-worker.sh"]:::backend
        SupervisorConf["supervisor-queue-worker.conf"]:::backend
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        GutenbergAPI["Project Gutenberg API"]:::external
        PMCApi["PMC API"]:::external
        PubMedAPI["PubMed API"]:::external
        LibreTranslateAPI["LibreTranslate API"]:::external
    end

    %% Database & Storage
    subgraph "Persistence"
        direction TB
        Database["MySQL/PostgreSQL"]:::data
        StorageFiles["File Storage"]:::storage
        LogsCache["Logs & Cache"]:::storage
    end

    %% Client Assets
    subgraph "Frontend Assets"
        direction TB
        AppJS["app.js"]:::ui
        BootstrapJS["bootstrap.js"]:::ui
        SearchBlade["Search Blade Views"]:::ui
        FilamentPages["Filament Pages Views"]:::ui
        FilamentCSS["public/css/filament/app.css"]:::ui
        FilamentJS["public/js/filament/app.js"]:::ui
        EchoJS["echo.js"]:::ui
    end

    %% Connections - Public Search Flow
    PublicSearchUI -->|HTTP POST| RoutesWeb
    RoutesWeb -->|calls| PublicSearchController
    PublicSearchController -->|enqueue| SearchJob
    SearchJob -->|reads config| ConfigQueue
    SearchJob -->|executes| ExternalApiService
    ExternalApiService -->|calls| GutenbergAPI
    ExternalApiService -->|calls| PMCApi
    ExternalApiService -->|calls| PubMedAPI
    ExternalApiService -->|send to| TranslationService
    TranslationService -->|HTTP| LibreTranslateAPI
    TranslationService -->|returns results| SearchJob
    SearchJob -->|fires event| SearchResultsUpdated
    SearchResultsUpdated -->|broadcast via| EchoJS
    EchoJS -->|push to| PublicSearchUI

    %% Connections - Admin UI Flow
    FilamentAdminUI -->|HTTP| RoutesWeb
    RoutesWeb -->|calls| BaseController
    BaseController -->|CRUD| EloquentModels
    EloquentModels --> Database

    %% Console triggers
    StartServicesCmd -->|starts| SupervisorConf
    SupervisorConf -->|manages| StartSearchWorker

    %% Persistence
    Database -->|stores| Migrations
    StorageFiles -->|stores| PDFReports[Blade PDF Views]:::service
    LogsCache -->|stores| storageLogs[storage/app/public & logs]:::storage

    %% Class Definitions
    classDef ui fill:#D5E8D4,stroke:#82B366,color:#274E13;
    classDef backend fill:#FFF2CC,stroke:#D6B656,color:#8C6E31;
    classDef service fill:#DAE8FC,stroke:#6C8EBF,color:#0B5394;
    classDef data fill:#F8CECC,stroke:#B85450,color:#741B47;
    classDef queue fill:#E1D5E7,stroke:#9673A6,color:#4C1130;
    classDef external fill:#E1D5E7,stroke:#6C8EBF,color:#0B5394;
    classDef storage fill:#FFE6CC,stroke:#D79B00,color:#874E04;

    %% Click Events
    click SearchBlade "https://github.com/asistente-informatica-enec/sigb/blob/main/resources/views/Search/search.blade.php"
    click SearchBlade "https://github.com/asistente-informatica-enec/sigb/blob/main/resources/views/Search/async-search.blade.php"
    click SearchBlade "https://github.com/asistente-informatica-enec/sigb/blob/main/resources/views/Search/results.blade.php"
    click SearchBlade "https://github.com/asistente-informatica-enec/sigb/blob/main/resources/views/Search/view.blade.php"
    click AppJS "https://github.com/asistente-informatica-enec/sigb/blob/main/resources/js/app.js"
    click BootstrapJS "https://github.com/asistente-informatica-enec/sigb/blob/main/resources/js/bootstrap.js"

    click FilamentPages "https://github.com/asistente-informatica-enec/sigb/blob/main/resources/views/filament/pages/*.blade.php"
    click FilamentCSS "https://github.com/asistente-informatica-enec/sigb/blob/main/public/css/filament/filament/app.css"
    click FilamentJS "https://github.com/asistente-informatica-enec/sigb/blob/main/public/js/filament/filament/app.js"
    click EchoJS "https://github.com/asistente-informatica-enec/sigb/blob/main/public/js/filament/filament/echo.js"

    click RoutesWeb "https://github.com/asistente-informatica-enec/sigb/blob/main/routes/web.php"
    click RoutesAPI "https://github.com/asistente-informatica-enec/sigb/blob/main/routes/api.php"
    click PublicSearchController "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Http/Controllers/PublicSearchController.php"
    click BaseController "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Http/Controllers/Controller.php"

    click ExternalApiService "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Services/ExternalApiService.php"
    click TranslationService "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Services/TranslationService.php"

    click EloquentModels "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Models/*.php"
    click Migrations "https://github.com/asistente-informatica-enec/sigb/blob/main/database/migrations/*.php"

    click SearchJob "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Jobs/SearchExternalApisJob.php"
    click ConfigQueue "https://github.com/asistente-informatica-enec/sigb/blob/main/config/queue.php"
    click StartSearchWorker "https://github.com/asistente-informatica-enec/sigb/blob/main/start-search-worker.sh"
    click SupervisorConf "https://github.com/asistente-informatica-enec/sigb/blob/main/supervisor-queue-worker.conf"

    click SearchResultsUpdated "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Events/SearchResultsUpdated.php"
    click BroadcastProvider "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Providers/BroadcastServiceProvider.php"
    click ConfigBroadcasting "https://github.com/asistente-informatica-enec/sigb/blob/main/config/broadcasting.php"

    click ProcessSearchQueue "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Console/Commands/ProcessSearchQueue.php"
    click StartServicesCmd "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Console/Commands/StartServices.php"
    click TestAsyncSearchCmd "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Console/Commands/TestAsyncSearch.php"
    click TestLibreTranslateCmd "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Console/Commands/TestLibreTranslate.php"
    click ConsoleKernel "https://github.com/asistente-informatica-enec/sigb/blob/main/app/Console/Kernel.php"

    click PDFReports "https://github.com/asistente-informatica-enec/sigb/blob/main/resources/views/pdf/*.blade.php"
    click PDFReports "https://github.com/asistente-informatica-enec/sigb/blob/main/resources/views/reports/pdf.blade.php"

    click StorageFiles "https://github.com/asistente-informatica-enec/sigb/tree/main/storage/app/public"
    click LogsCache "https://github.com/asistente-informatica-enec/sigb/tree/main/storage/logs"
```
