# dannypatt/flask-ticket-analyzer architecture

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

- Interactive diagram: https://gitdiagram.com/dannypatt/flask-ticket-analyzer
- Repository: https://github.com/dannypatt/flask-ticket-analyzer

## Overview

Para representar con claridad y precisión la arquitectura del proyecto “Analizador y Clasificador de Tickets IT con Flask y Ollama”, sigue estos pasos:

##### Identificar el tipo de proyecto y su propósito
- Tipo: Aplicación web full-stack ligera, enfocada en procesamiento y clasificación de tickets almacenados en Excel.
- Propósito: Proveer una UI basada en Flask para subir archivos `.xlsx`, procesarlos localmente usando modelos LLM a través de Ollama y devolver un archivo con columnas de resumen y categoría.

##### Análisis de la estructura de archivos
- Top-level:
- `app.py`: punto de entrada del servidor Flask, define rutas HTTP y lógica de subida/descarga.
- `processing_logic.py`: módulo central que implementa la lectura de Excel con Pandas, llamadas al LLM via Ollama CLI/HTTP, procesamiento paralelo (`ThreadPoolExecutor`), limpieza de HTML con BeautifulSoup, y generación de un nuevo Excel.
- `templates/`: vistas Jinja2 (`index.html`, `processing.html`).
- Notebooks (`*.ipynb`): demos o experimentos, no forman parte de la ejecución de producción.
- `requirements.txt`: dependencias (Flask, Pandas, BeautifulSoup4…).
- Carpetas requeridas (no listadas en el file tree, pero definidas en README): `uploads/` y `processed/`.

##### Componentes principales para el diagrama
a. Frontend Web
- Navegador del usuario:
- Formulario de subida
- Página de progreso (JavaScript polling)
- Enlace de descarga
b. Backend Flask
- app.py:
- Rutas: `/` (subida), `/process` (arranca procesamiento), `/status` (consulta progreso), `/download`
- Orquestación de flujos
c. Módulo de Procesamiento
- processing_logic.py:
- Lectura y validación de columnas
- División de tickets en tareas
- `ThreadPoolExecutor` para concurrencia
- Invocación a Ollama
d. Servicio LLM Local (Ollama)
- Container/Proceso Ollama (`ollama serve`):
- Recibe peticiones de generación de texto (summaries, clases)
- Modelo por defecto: Gemma 3 (configurable)
e. Almacenamiento de Archivos
- Sistema de ficheros local:
- `uploads/`: archivos entrantes
- `processed/`: resultados generados
f. (Opcional) Comunicación de Estado
- Endpoint `/status` + JavaScript polling para actualización de progreso en la UI

##### Relaciones e interacciones
- El usuario sube un `.xlsx` → Flask guarda en `uploads/` → `app.py` invoca `processing_logic.process_file()` →
- `processing_logic` lee el archivo con Pandas → envía peticiones concurrentes al Servicio Ollama → recibe resúmenes y categorías → escribe nuevo Excel en `processed/` →
- Flask notifica a la UI (mediante polling) del avance y, al terminar, ofrece un enlace a `/download`.

##### Patrones y principios
- Separación de capas:
- Presentación (templates + JS)
- Orquestación (Flask)
- Lógica de negocio (processing_logic)
- Servicio externo (Ollama)
- Persistencia simple (filesystem)
- Diseño orientado a módulos: cada responsabilidad en un archivo.
- Concurrencia controlada: uso de `ThreadPoolExecutor` para no bloquear el servidor web.

##### Tecnologías clave
- Flask (WSGI)
- Jinja2 para templates
- Pandas para manipulación de datos
- concurrent.futures para procesamiento paralelo
- Ollama para LLM local
- BeautifulSoup4 para limpiar/parsear HTML
- JavaScript (fetch/polling) en la UI

##### Cómo dibujar el diagrama
- Usa rectángulos para componentes internos (Flask App, processing_logic).
- Usa cilindros o cajas estilo “filesystem” para `uploads/` y `processed/`.
- Usa un componente externo (paralelogramo o nube) para “Ollama LLM Service”.
- Representa al “Client Browser” (paralelogramo) con flechas HTTP:
- Flecha solidaria “POST /upload” → Flask
- Flecha “GET /status” (recurrente)
- Flecha “GET /download”
- Entre Flask y processing_logic, usa una flecha interna “process_file()”.
- Entre processing_logic y Ollama, flechas paralelas etiquetadas “LLM Inference Request / Response”.
- Indica flujo de datos: subida → almacenamiento → procesamiento → almacenamiento → descarga.
- Azul para componentes web (Browser, Flask)
- Verde para módulo de procesamiento
- Naranja para servicio LLM externo
- Gris para storage (filesystem)
- Etiqueta cada conexión con el protocolo o llamada (HTTP, ThreadPoolExecutor, filesystem I/O).

##### Detalles finales
- Incluye leyenda de colores/formas.
- Asegúrate de que cada componente tenga un nombre claro y un pequeño descriptor (p.ej., “Flask App (app.py + routes)”).
- Añade notas sobre configuraciones clave (p.ej., modelo configurable, número de hilos).

Con esta guía, podrás plasmar un diagrama detallado que muestre todas las piezas de la arquitectura, sus interacciones y tecnologías, de forma clara y comprensible.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client
    Browser["Client Browser"]:::web

    %% Backend
    FlaskApp["Flask App\n(app.py + routes)"]:::web

    %% Processing
    ProcessingModule["Processing Module\n(processing_logic.py)"]:::processing

    %% LLM Service
    Ollama["Ollama LLM Service"]:::llm

    %% Storage
    subgraph "Filesystem Storage"
        UploadDir["uploads/"]:::storage
        ProcessedDir["processed/"]:::storage
    end

    %% Project Files
    subgraph "Project Files"
        IndexTemplate["index.html"]:::web
        ProcessingTemplate["processing.html"]:::web
        Requirements["requirements.txt"]:::file
        README["README.md"]:::file
    end

    %% Connections
    Browser -->|"POST /upload"| FlaskApp
    FlaskApp -->|"save file\nfilesystem I/O"| UploadDir
    FlaskApp -->|"process_file()"| ProcessingModule
    ProcessingModule -->|"read file\nPandas"| UploadDir
    ProcessingModule -->|"ThreadPoolExecutor\nLLM Inference Request/Response"| Ollama
    ProcessingModule -->|"write file\nPandas"| ProcessedDir
    FlaskApp -->|"GET /status\nPolling"| Browser
    FlaskApp -->|"GET /download"| Browser
    FlaskApp -->|"serve file\nfilesystem I/O"| ProcessedDir

    FlaskApp --> IndexTemplate
    FlaskApp --> ProcessingTemplate

    FlaskApp -.-> Requirements
    FlaskApp -.-> README

    %% Click Events
    click IndexTemplate "https://github.com/dannypatt/flask-ticket-analyzer/blob/main/templates/index.html"
    click ProcessingTemplate "https://github.com/dannypatt/flask-ticket-analyzer/blob/main/templates/processing.html"
    click FlaskApp "https://github.com/dannypatt/flask-ticket-analyzer/blob/main/app.py"
    click ProcessingModule "https://github.com/dannypatt/flask-ticket-analyzer/blob/main/processing_logic.py"
    click Requirements "https://github.com/dannypatt/flask-ticket-analyzer/blob/main/requirements.txt"
    click README "https://github.com/dannypatt/flask-ticket-analyzer/blob/main/README.md"

    %% Styles
    classDef web fill:#D0E6FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef processing fill:#DFFFE0,stroke:#228B22,color:#228B22,stroke-width:1px;
    classDef llm fill:#FFE5B4,stroke:#FFA500,color:#A06500,stroke-width:1px;
    classDef storage fill:#F0F0F0,stroke:#999999,color:#333333,stroke-width:1px;
    classDef file fill:#ECECEC,stroke:#AAAAAA,color:#555555,stroke-width:1px;
```
