# jhonvilcarana/facturia_proyect architecture

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

- Interactive diagram: https://gitdiagram.com/jhonvilcarana/facturia_proyect
- Repository: https://github.com/jhonvilcarana/facturia_proyect

## Overview

##### Project Type and Purpose
- FacturIA is a full-stack, data-processing application that automates invoice ingestion, extraction, storage, and visualization. It comprises:
- A document ingestion and processing pipeline (PDFs + images → structured data via OCR and AI).
- A backend REST API (Flask) exposing processed invoices.
- A relational database (PostgreSQL) for data persistence.
- An analytical dashboard (Power BI) for reporting.

##### File Structure Analysis
- Top-level scripts:
- main.py – orchestrates the invoice scanning, OCR (Tesseract), PDF text extraction (PyMuPDF), AI prompts, currency conversion, and DB insertion.
- funciones.py – utility functions for parsing, OCR, data normalization, error handling.
- prompt.py – houses the OpenAI GPT-4o-mini prompt templates and parsing logic.
- api_facturas.py – Flask app exposing GET /facturas endpoint.
- Folders:
- facturas/YYYY-MM/ – input folder for raw invoice files (PDF, JPG, PNG, TIFF, BMP).
- Dashboard_PowerBI/ – Power BI .pbix and resources for visualization.
- Config & Dependency files:
- .env.example – environment variables for OpenAI API key and DATABASE_URL.
- requirements.txt, entorno.yml – Python dependencies.

a. Ingestion Layer
- Invoice Storage (Local FS – facturas/ folder)
- File Watcher or Batch Script (main.py)
b. Processing Layer
- PDF Text Extractor (PyMuPDF)
- OCR Engine (Tesseract via pytesseract + Pillow)
- AI Processor (OpenAI GPT-4o-mini via prompt.py)
- Currency Converter & Data Cleaner (funciones.py)
c. Persistence Layer
- PostgreSQL DB (SQLAlchemy + psycopg2)
- DB Schema (invoices table: id, fecha, proveedor, importe, concepto, moneda)
d. API Layer
- Flask App (api_facturas.py)
- Endpoint: GET /facturas → returns JSON of processed records
e. Visualization Layer
- Power BI Dashboard (FacturIA.pbix)
- Connects to PostgreSQL to render charts and KPIs
f. External Services
- OpenAI API
- Tesseract Engine

Relationships:
- main.py reads files → passes to PyMuPDF or pytesseract → structured output → prompt.py enriches via OpenAI → funciones.py normalizes data → inserts into PostgreSQL.
- api_facturas.py queries PostgreSQL → returns JSON to clients.
- Power BI connects to PostgreSQL → fetches tables → visualizes data.

##### Architectural Patterns & Principles
- Layered Architecture: clear separation between ingestion, processing, persistence, API, and visualization.
- Single Responsibility: each script/folder handles a specific concern.
- Configuration via Env Vars: decoupled secrets and endpoints.
- Batch vs. Real-time: invoice folder polling (batch) vs. REST API (real-time).
- Extensibility: easily add new file types, languages, or AI models.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Ingestion Layer
    subgraph "Ingestion Layer"
        direction TB
        InvoiceStorage["Invoice Storage \n(Local FS)"]:::ingestion
        FileWatcher["Batch Script \n(main.py)"]:::ingestion
    end

    %% Processing Layer
    subgraph "Processing Layer"
        direction TB
        PDFExtractor["PDF Text Extractor \n(PyMuPDF)"]:::processing
        OCREngine["OCR Engine \n(pytesseract + Pillow)"]:::processing
        AIProcessor["AI Processor \n(OpenAI GPT-4o-mini)"]:::processing
        DataCleaner["Currency Converter & Data Cleaner \n(funciones.py)"]:::processing
    end

    %% Persistence Layer
    subgraph "Persistence Layer"
        direction TB
        PostgreSQL["PostgreSQL DB \n(SQLAlchemy + psycopg2)"]:::persistence
        DBSample["SQLite Sample DBs"]:::persistence
    end

    %% API Layer
    subgraph "API Layer"
        direction TB
        FlaskAPI["Flask App \n(GET /facturas)"]:::api
    end

    %% Visualization Layer
    subgraph "Visualization Layer"
        direction TB
        PowerBI["Power BI Dashboard \n(FacturIA.pbix)"]:::viz
    end

    %% Configuration
    subgraph "Configuration"
        direction TB
        EnvConfig["Env Config \n(.env.example)"]:::config
        Requirements["Requirements \n(requirements.txt)"]:::config
        Entorno["Conda Env \n(entorno.yml)"]:::config
    end

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

    %% Data Flow
    InvoiceStorage --> FileWatcher
    FileWatcher --> PDFExtractor
    FileWatcher --> OCREngine
    PDFExtractor --> AIProcessor
    OCREngine --> AIProcessor
    AIProcessor --> DataCleaner
    DataCleaner --> PostgreSQL
    DBSample --> PostgreSQL
    PostgreSQL --> FlaskAPI
    PostgreSQL --> PowerBI
    FlaskAPI -->|"Clients" | PowerBI

    %% Config Dependencies
    EnvConfig --> FileWatcher
    EnvConfig --> AIProcessor
    EnvConfig --> FlaskAPI
    Requirements --> FileWatcher
    Entorno --> FileWatcher

    %% External Dependencies
    OpenAI --> AIProcessor
    Tesseract --> OCREngine

    %% Click Events
    click InvoiceStorage "https://github.com/jhonvilcarana/facturia_proyect/tree/main/FacturIA/facturas/"
    click FileWatcher "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/main.py"
    click PDFExtractor "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/main.py"
    click OCREngine "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/funciones.py"
    click DataCleaner "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/funciones.py"
    click AIProcessor "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/prompt.py"
    click EnvConfig "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/.env.example"
    click Requirements "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/requirements.txt"
    click Entorno "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/entorno.yml"
    click FlaskAPI "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/api_facturas.py"
    click PowerBI "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/Dashboard_PowerBI/Power_BI/FacturIA.pbix"
    click DBSample "https://github.com/jhonvilcarana/facturia_proyect/blob/main/FacturIA/facturas.db"

    %% Styles
    classDef ingestion fill:#B3CDE3,stroke:#034F84,color:#000
    classDef processing fill:#FBB4AE,stroke:#B34D4D,color:#000
    classDef persistence fill:#C7E9C0,stroke:#238B45,color:#000
    classDef api fill:#D9D2E9,stroke:#6A51A3,color:#000
    classDef viz fill:#B2DFDB,stroke:#00796B,color:#000
    classDef config fill:#FFF2B2,stroke:#E69F00,color:#000
    classDef external fill:#E0E0E0,stroke:#6D6D6D,color:#000
```
