How dannypatt/flask-ticket-analyzer works
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.