How tomaxido/validocu works
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.