# jagonzalezmaita/facturas-ocr-llm-powerbi architecture

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

- Interactive diagram: https://gitdiagram.com/jagonzalezmaita/facturas-ocr-llm-powerbi
- Repository: https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi

## Overview

##### Project type and purpose
- Este es un **pipeline batch offline** para transformar facturas PDF en datos estructurados, usando OCR (PaddleOCR), un LLM local (Nous Hermes 2 – Mistral 7B), SQLite y, para visualización, un dashboard de Power BI.
- El usuario inicia el proceso colocando PDFs en carpetas por año/mes; luego ejecuta `python -m src.main`.

##### Analizar la estructura de archivos
- Top‐level:
– dashboard/ → definición y recursos Power BI
– data/ → entrada (facturas/sin_procesar), salida (output JSON e imágenes) y base de datos SQLite
– models/ → binarios de OCR y LLM
– src/ → módulos de pipeline (ocr, llm, postprocessor, db, utils, config, common) y entrypoint main.py
– logs/, tests/
- Patrón arquitectónico: **pipeline modular** (secuencia de stages), manejo de archivos en FS, DB como store final.

##### Inspeccionar README para insights
- Se describe paso a paso: OCR → preprocesamiento → prompt → invocación LLM → postprocesamiento → inserción en SQLite → dashboard Power BI vía ODBC.
- Dependencias: Python 3.13, PaddleOCR, llama-cpp-python, SQLite ODBC.

##### Crear el diagrama de sistema
a. Componentes principales (cada uno como caja):
1. File System (FS):
- Ingreso de PDFs
- Output FS: imágenes OCR, JSONs OCR/LLM/post
2. OCR Processor (PaddleOCR)
3. Preprocessor & Prompt Builder
4. LLM Inference (Nous Hermes 2 local)
5. Postprocessor (validaciones y formateo)
6. SQLite Database (data/database/facturas.db)
7. Power BI Dashboard (dashboard/, ODBC DSN)
8. Logging & Tests (logs/, tests/)
b. Relaciones / flujo:
- PDFs → OCR → JSON OCR → Preprocessor → Prompt → LLM → JSON LLM → Postprocessor → JSON final → DB
- Power BI se conecta a DB
- Logs se generan en cada stage
c. Patrones / principios:
- Pipeline secuencial de etapas (arquitectura por capas)
- Separación de responsabilidades en módulos Python
- Offline batch, FS-driven
d. Tecnologías clave:
- PaddleOCR, llama-cpp-python, SQLite, ODBC, Power BI

##### Guía de estilo para el diagrama
- Use **cajas rectangulares** para cada componente de cálculo o módulo de código.
- Use **cilindros** para bases de datos (SQLite).
- Use **nubes** o íconos especiales para servicios externos (Power BI, ODBC).
- Conecte con flechas direccionales que indiquen el flujo de datos (de PDFs a DB).
- Asigne **colores**:
– Azul para procesamiento (OCR, LLM, post)
– Verde para almacenamiento (FS, DB)
– Naranja para consumo/visualización (Power BI)
- Etiquete cada flecha con el tipo de artefacto (por ejemplo: “PDF”, “OCR‐JSON”, “JSON final”, “ODBC query”).

##### Detalles y recomendaciones
- Asegúrese de mostrar carpetas clave (`data/facturas`, `data/output`, `data/database`).
- Demarque módulos Python principales (`src/ocr/ocr_reader.py`, `src/llm/…`, `src/db/db_manager.py`).
- Incluya los modelos en “models/” como repositorio offline.
- Añada notas sobre configuración (.env, requirements.txt) y tests automatizados.

Con este esquema, el diagrama reflejará con precisión la **arquitectura en capas** del pipeline de facturas OCR+LLM, mostrando todas las interacciones y tecnologías involucradas.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% File System
    subgraph "File System Storage"
        FSInput["Input PDFs\n(data/facturas/sin_procesar/)"]:::storage
        FSOutput["Processed Outputs\n(data/output/)"]:::storage
        DBFile["SQLite DB\n(facturas.db)"]:::storage
    end

    %% Pipeline Processing
    subgraph "Processing Pipeline"
        OCR["OCR Processor\n(src/ocr/ocr_reader.py)"]:::processing
        Preproc["Preprocessor & Prompt Builder\n(src/llm/preprocessor.py)"]:::processing
        LLM["LLM Inference\n(src/llm/parse_llm.py)"]:::processing
        Postproc["Postprocessor\n(src/llm/postprocessor.py)"]:::processing
    end

    %% Visualization
    PowerBI["Power BI Dashboard\n(dashboard/)"]:::viz

    %% Support Modules
    subgraph "Support Modules"
        Config["Configuration\n(src/config/settings.py)"]:::util
        Logger["Logging\n(src/config/logger.py)"]:::util
        FileMgr["File Manager\n(src/utils/file_manager.py)"]:::util
        Exceptions["Common Exceptions\n(src/common/exceptions.py)"]:::util
        DataModel["Data Models\n(src/data_models/factura_model.py)"]:::util
        Tests["Automated Tests\n(tests/test_pipeline.py)"]:::util
    end

    %% Flow
    FSInput -->|"PDF"| OCR
    OCR -->|"OCR-JSON"| FSOutput
    OCR -->|"OCR-JSON"| Preproc
    Preproc -->|"Prompt"| LLM
    LLM -->|"LLM-JSON"| Postproc
    Postproc -->|"Final JSON"| FSOutput
    Postproc -->|"Insert"| DBFile
    DBFile -->|"ODBC Query"| PowerBI

    %% Logging connections
    OCR --> Logger
    Preproc --> Logger
    LLM --> Logger
    Postproc --> Logger

    %% Support usage
    Preproc --> Config
    OCR --> FileMgr
    Postproc --> Exceptions
    OCR --> DataModel

    %% Click Events
    click FSInput "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/tree/main/data/facturas/sin_procesar/"
    click FSOutput "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/tree/main/data/output/"
    click DBFile "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/data/database/facturas.db"
    click OCR "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/src/ocr/ocr_reader.py"
    click OCR "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/tree/main/models/PaddleOCR/"
    click Preproc "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/src/llm/preprocessor.py"
    click LLM "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/src/llm/parse_llm.py"
    click LLM "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/tree/main/models/Nous-Hermes-2-Mistral-7B-DPO/"
    click Postproc "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/src/llm/postprocessor.py"
    click PowerBI "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/tree/main/dashboard/"
    click PowerBI "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/tree/main/dashboard/dashboard_facturas.Report/"
    click PowerBI "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/tree/main/dashboard/dashboard_facturas.SemanticModel/"
    click Logger "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/src/config/logger.py"
    click Config "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/src/config/settings.py"
    click Config "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/.env.example"
    click FileMgr "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/src/utils/file_manager.py"
    click Exceptions "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/src/common/exceptions.py"
    click DataModel "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/src/data_models/factura_model.py"
    click Tests "https://github.com/jagonzalezmaita/facturas-ocr-llm-powerbi/blob/main/tests/test_pipeline.py"

    %% Styles
    classDef processing fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef storage fill:#90EE90,stroke:#000,stroke-width:1px
    classDef viz fill:#FFA500,stroke:#000,stroke-width:1px
    classDef util fill:#D3D3D3,stroke:#000,stroke-width:1px
```
