# tomaxido/validocu architecture

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

- Interactive diagram: https://gitdiagram.com/tomaxido/validocu
- Repository: https://github.com/tomaxido/validocu

## Overview

##### Project type and purpose
- This is a hybrid full-stack web application plus a standalone Python utility:
- Frontend “validocu” (React, Vite) for user interface.
- Backend “backend” (Laravel, PHP, PostgreSQL) exposing REST/HTTP endpoints and handling business logic, authentication, data persistence, queues, and file storage.
- A separate “generador-de-contratos-fake” Python script for bulk contract generation using OCR/Poppler.

##### File structure
- Top-level directories:
- backend/ – Laravel monolithic backend
- validocu/ – React single-page application
- generador-de-contratos-fake/ – Python CLI utility
- backend/ patterns:
- app/Http/Controllers – MVC controllers
- app/Models – Eloquent models
- config/, bootstrap/, routes/ – framework wiring
- database/ – migrations, factories, seeders
- storage/ – file uploads, cache, logs, session data
- public/ – web root (index.php)
- queue, mail, cache configured via .env
- validocu/ patterns:
- src/ – React components, assets
- public/ – static HTML, favicon
- config: tsconfig.*, vite.config
- Python utility:
- Multiple .py modules orchestrating PDF→images, OCR labeling, contract structure & output.

##### Extract insights from README
- Backend stack: PHP 8.3, Laravel 11, PostgreSQL.
- Frontend stack: Node.js, React.
- Generator: Python 3.13 + virtualenv + Poppler for PDF operations.

##### Main components
a. Frontend (validocu SPA)
- React app served via Vite (development) or static build on CDN/Web server.
- Interacts over HTTPS with Laravel API.
b. Backend (Laravel monolith)
- HTTP layer: Router → Controllers
- Business layer: Services, Providers
- Persistence: PostgreSQL database, Cache (redis or file), Job Queue (database driver or Redis)
- Storage: local or S3 (public/private filesystem disks)
- Email: Mail driver configured in services
- Tests (unit/feature) – not part of runtime but indicate test harness
c. External services
- PostgreSQL server
- (Optional) Redis for cache/queue
- SMTP or third-party email provider
- Object storage (local disk or S3)
d. Python utility (generador-de-contratos-fake)
- Standalone CLI
- Uses Poppler CLI (pdfinfo, pdftoppm) for PDF → images
- OCR module generates labels across multi-page docs
- Outputs synthetic contract files (PDFs, JSON metadata)

##### Relationships and interactions
- User’s browser → React SPA (HTTPS).
- SPA → Laravel API endpoints (REST) for authentication, data fetch, file upload.
- Laravel → PostgreSQL for data CRUD.
- Laravel → Cache/Queue for background jobs.
- Laravel → Storage for file persistence (uploads, generated reports).
- Laravel → Mail service for notifications.
- Operator runs Python CLI separately; it may consume stored templates and produce artifacts that can be imported by the backend or uploaded via the API.

##### Architectural patterns and design principles
- MVC pattern in Laravel (Models, Views for blade templates, Controllers).
- RESTful API separation: clear boundary between client and server.
- Single-page application architecture on the frontend.
- CLI utility as a separate bounded context/micro-tool.
- Use of environment configurations for credentials, service endpoints.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Browser
    User["User's Browser"]:::external
    User -->|"HTTPS"| ReactApp

    %% Frontend Layer
    subgraph "Frontend (validocu SPA)"
        direction TB
        ReactApp["React SPA (Vite)"]:::frontend
        PublicFiles["Public Static Files"]:::frontend
        ViteConfig["Vite & TS Config"]:::frontend
        Components["React Components & Assets"]:::frontend
    end

    ReactApp -->|serves| PublicFiles
    ReactApp -->|built with| ViteConfig
    ReactApp -->|renders| Components
    ReactApp -->|"HTTPS REST"| LaravelAPI

    %% Backend Layer
    subgraph "Backend (Laravel API)" 
        direction TB
        Entry["API Entry Point\n(index.php)"]:::backend
        Routing["HTTP Routing"]:::backend
        Controllers["MVC Controllers"]:::backend
        Models["Eloquent Models"]:::backend
        Providers["Service Providers"]:::backend
        Config["Configuration Files"]:::backend
        Migrations["DB Migrations & Factories & Seeders"]:::backend
        StorageFW["Framework Storage (cache/sessions/views/logs)"]:::backend
        FileDisks["File Storage Disks"]:::backend
        QueueCacheConfig["Cache & Queue Config"]:::backend
        MailConfig["Mail Configuration"]:::backend
        Tests["Testing Harness"]:::backend
        Composer["Composer Dependencies"]:::backend
    end

    LaravelAPI["Laravel API"]:::backend

    ReactApp -->|"REST API calls"| LaravelAPI
    LaravelAPI --> Entry
    Entry --> Routing
    Routing --> Controllers
    Controllers --> Providers
    Controllers --> Models
    Providers --> Config
    Models --> Migrations
    Models -->|reads/writes| PostgreSQLDB
    LaravelAPI -->|enqueue jobs| RedisCache
    LaravelAPI -->|cache lookup| RedisCache
    LaravelAPI -->|store files| FileDisks
    LaravelAPI -->|use storage| StorageFW
    LaravelAPI -->|send email| SMTPService
    LaravelAPI -->|environment| Config
    LaravelAPI -->|tests| Tests
    LaravelAPI -->|autoload| Composer

    %% Data Stores
    PostgreSQLDB["PostgreSQL"]:::database
    RedisCache["Redis\n(cache & queue)"]:::external
    FileDisks --> S3Storage["S3 / Local Storage"]:::external
    SMTPService["SMTP / Email Service"]:::external

    %% Python Utility
    subgraph "Python CLI (generador-de-contratos-fake)" 
        direction TB
        CLI["CLI Entrypoint"]:::python
        PDF2Img["PDF to Images Module\n(Poppler)"]:::python
        OCR["OCR Labeling Module"]:::python
        Structures["Contract Structure Definitions"]:::python
        Generator["Contract Generation Orchestrator"]:::python
        Drawer["Label Drawing Utility"]:::python
        Requirements["Requirements.txt"]:::python
    end

    CLI --> PDF2Img
    CLI --> OCR
    CLI --> Structures
    CLI --> Generator
    CLI --> Drawer
    CLI --> Requirements
    CLI -.->|outputs| OutputArtifacts["Generated PDFs & JSON"]:::external
    OutputArtifacts -.->|import via API| LaravelAPI

    %% Click Events
    click ReactApp "https://github.com/tomaxido/validocu/tree/main/validocu/"
    click Components "https://github.com/tomaxido/validocu/tree/main/validocu/src/"
    click PublicFiles "https://github.com/tomaxido/validocu/tree/main/validocu/public/"
    click ViteConfig "https://github.com/tomaxido/validocu/blob/main/validocu/vite.config.ts"
    click Entry "https://github.com/tomaxido/validocu/blob/main/backend/public/index.php"
    click Routing "https://github.com/tomaxido/validocu/blob/main/backend/routes/web.php"
    click Controllers "https://github.com/tomaxido/validocu/blob/main/backend/app/Http/Controllers/Controller.php"
    click Models "https://github.com/tomaxido/validocu/tree/main/backend/app/Models/"
    click Providers "https://github.com/tomaxido/validocu/blob/main/backend/app/Providers/AppServiceProvider.php"
    click Config "https://github.com/tomaxido/validocu/blob/main/backend/config/app.php"
    click Migrations "https://github.com/tomaxido/validocu/tree/main/backend/database/migrations/"
    click FileDisks "https://github.com/tomaxido/validocu/tree/main/backend/storage/app/public/"
    click StorageFW "https://github.com/tomaxido/validocu/tree/main/backend/storage/framework/cache/"
    click MailConfig "https://github.com/tomaxido/validocu/blob/main/backend/config/mail.php"
    click Tests "https://github.com/tomaxido/validocu/tree/main/backend/tests/Unit/"
    click Composer "https://github.com/tomaxido/validocu/blob/main/backend/composer.json"
    click CLI "https://github.com/tomaxido/validocu/tree/main/generador-de-contratos-fake/"
    click PDF2Img "https://github.com/tomaxido/validocu/blob/main/generador-de-contratos-fake/pdf_to_images.py"
    click OCR "https://github.com/tomaxido/validocu/blob/main/generador-de-contratos-fake/ocr_label_multi_doc.py"
    click Structures "https://github.com/tomaxido/validocu/blob/main/generador-de-contratos-fake/estructuras_de_contratos.py"
    click Generator "https://github.com/tomaxido/validocu/blob/main/generador-de-contratos-fake/generador_de_contratos.py"
    click Drawer "https://github.com/tomaxido/validocu/blob/main/generador-de-contratos-fake/dibujar_etiquetas.py"
    click Requirements "https://github.com/tomaxido/validocu/blob/main/generador-de-contratos-fake/requirements.txt"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#004085,color:#004085,stroke-width:1px;
    classDef backend fill:#d4edda,stroke:#155724,color:#155724,stroke-width:1px;
    classDef database fill:#fff3cd,stroke:#856404,color:#856404,stroke-width:1px;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d,stroke-width:1px,stroke-dasharray: 5 5;
    classDef python fill:#f5e6ff,stroke:#5e0580,color:#5e0580,stroke-width:1px,stroke-dasharray: 3 3;
```
