# joacominatel/escaneo-facturas-scratch architecture

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

- Interactive diagram: https://gitdiagram.com/joacominatel/escaneo-facturas-scratch
- Repository: https://github.com/joacominatel/escaneo-facturas-scratch

## Overview

##### Project type and purpose
- This is a containerized, full-stack invoice-processing system.
- It uses a Next.js frontend, a Flask REST API backend, a Celery worker for asynchronous processing, MariaDB for storage, Redis as broker/cache, and external OCR (Tesseract) plus OpenAI for intelligent data extraction.

##### File structure
- Top-level directories:
- app/ (Flask application subdivided into api/, core/, models/, services/, tasks/, prompts/, utils/)
- frontend/ (Next.js app with pages, components, hooks, contexts, and lib/)
- migrations/ (Alembic scripts for DB schema)
- docker/ + docker-compose.yml (service definitions and Dockerfiles)
- Patterns & configurations:
- app/api: individual Flask endpoints (invoice upload, list, preview, confirm, retry, download, etc.)
- app/core: configuration, Celery app setup, Flask extensions (CORS, SocketIO)
- app/services & tasks: OCR and OpenAI calls encapsulated in services, Celery task definitions
- WebSocket support via Flask-SocketIO for real-time updates
- Docker Compose orchestrates six services (frontend, backend, worker, mariadb, redis, and optionally a volume or cache)

##### README for additional insights
- Confirms an asynchronous flow: user→API→queue→worker→DB→WebSocket→frontend
- Lists all major technologies/platforms and service boundaries
- Describes API endpoints and high-level processing steps

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Layers
    subgraph "Frontend Layer"
        direction TB
        User["User"]:::external
        Frontend["Next.js Frontend"]:::frontend
        Pages["Pages & Routes"]:::frontend
        Components["UI Components"]:::frontend
        APILib["API & WebSocket Clients"]:::frontend
        HooksContexts["Custom Hooks & Contexts"]:::frontend
    end

    subgraph "Backend Services"
        direction TB
        API["Flask REST API"]:::backend
        Extensions["Flask Extensions"]:::backend
        CeleryApp["Celery App Setup"]:::backend
        Config["App Configuration"]:::backend
        Tasks["Celery Worker"]:::backend
        OCRService["OCR Service (Tesseract)"]:::backend
        AIService["OpenAI Service"]:::backend
        FileUtil["File Extraction Utility"]:::backend
        Models["ORM Models"]:::backend
        Migrations["DB Migrations"]:::datastore
        RedisDb["Redis"]:::datastore
        MariaDb["MariaDB"]:::datastore
    end

    subgraph "External Services"
        direction TB
        Tesseract["Tesseract OCR"]:::external
        OpenAI["OpenAI API"]:::external
    end

    %% Connections
    User -->|"Uses UI"| Frontend
    Frontend -->|"HTTP /api/invoices/*"| API
    Frontend -->|"WebSocket invoice_updates"| API

    API -->|"Enqueue task"| RedisDb
    RedisDb -->|"Fetch task"| Tasks
    Tasks -->|"Acknowledge"| RedisDb

    Tasks -->|"Extract text"| Tesseract
    Tasks -->|"Extract data"| OpenAI
    Tasks -->|"Update records"| MariaDb

    Tasks -->|"Emit status"| API
    API -->|"WebSocket event"| Frontend

    Frontend -->|"PATCH/POST confirm,retry"| API
    API -->|"Update state"| MariaDb

    %% Infrastructure
    API --> Extensions
    API --> Config
    API --> Models
    API --> FileUtil
    API --> Migrations
    API --> CeleryApp
    Tasks --> OCRService
    Tasks --> AIService

    %% Click Events
    click Frontend "https://github.com/joacominatel/escaneo-facturas-scratch/tree/main/frontend/"
    click Pages "https://github.com/joacominatel/escaneo-facturas-scratch/tree/main/frontend/src/app/"
    click Components "https://github.com/joacominatel/escaneo-facturas-scratch/tree/main/frontend/src/components/"
    click APILib "https://github.com/joacominatel/escaneo-facturas-scratch/tree/main/frontend/src/lib/api/"
    click APILib "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/frontend/src/lib/ws/invoice-updates.ts"
    click HooksContexts "https://github.com/joacominatel/escaneo-facturas-scratch/tree/main/frontend/src/hooks/"
    click HooksContexts "https://github.com/joacominatel/escaneo-facturas-scratch/tree/main/frontend/src/contexts/"
    click API "https://github.com/joacominatel/escaneo-facturas-scratch/tree/main/app/api/"
    click Extensions "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/core/extensions.py"
    click CeleryApp "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/core/celery_app.py"
    click Config "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/core/config.py"
    click Models "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/models/invoice.py"
    click Models "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/models/invoice_data.py"
    click Models "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/models/invoice_log.py"
    click Models "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/models/invoice_status_summary.py"
    click OCRService "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/services/ocr_service.py"
    click AIService "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/services/openai_service.py"
    click Tasks "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/tasks/invoice_tasks.py"
    click FileUtil "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/app/utils/file_extractor.py"
    click Migrations "https://github.com/joacominatel/escaneo-facturas-scratch/tree/main/migrations/"
    click Migrations "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/migrations/env.py"
    click Migrations "https://github.com/joacominatel/escaneo-facturas-scratch/tree/main/migrations/versions/"
    click Migrations "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/alembic.ini"
    click Migrations "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/script.py.mako"
    click docker "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/docker-compose.yml"
    click docker "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/docker/backend.Dockerfile"
    click docker "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/docker/celery.Dockerfile"
    click docker "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/docker/frontend.Dockerfile"
    click runpy "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/run.py"
    click wsgi "https://github.com/joacominatel/escaneo-facturas-scratch/blob/main/wsgi.py"

    %% Styles
    classDef frontend fill:#D4E4FF,stroke:#0366d6,color:#0366d6
    classDef backend fill:#E4F4E1,stroke:#28A745,color:#155724
    classDef datastore fill:#FFE4B5,stroke:#FF8C00,color:#8B4513
    classDef external fill:#E2E3E5,stroke:#6C757D,color:#383D41
```
