El servicio All File Converter está diseñado como un sistema SaaS distribuido y escalable basado en la pila asíncrona moderna de Python 3.12. La arquitectura se divide en capas independientes: recepción de eventos de red, orquestación de tareas, ejecución aislada de procesos binarios pesados y el circuito analítico.

1. Pila tecnológica general y arquitectura del sistema

La plataforma se basa en principios de alto rendimiento (high-throughput), consumo mínimo de memoria y protección contra fallos:

  • Telegram Bot Framework: Aiogram 3.13, que opera en modo Webhook con validación de tokens secretos y filtros personalizados del ciclo de vida de los mensajes.
  • Puerta de enlace web y REST API: FastAPI basada en el servidor ASGI Uvicorn con transmisión asíncrona por secuencias de archivos binarios (FileResponse) y limpieza en segundo plano mediante BackgroundTasks.
  • Agente de colas y caché: Redis 7 (gestión de tareas de Celery, bloqueos contra condiciones de carrera, protección contra ataques de fuerza bruta, almacenamiento en caché de sesiones).
  • Ejecutor en segundo plano (Task Queue): Celery 5.4 con un grupo de trabajadores (workers) dedicado en un contenedor aislado converter_worker.
  • Base de datos: PostgreSQL 16 con la capa ORM SQLAlchemy 2.0 (asyncpg), un grupo de conexiones persistentes (20+10 overflow) y reintentos automáticos para transacciones fallidas (@db_retry).
  • Circuito de red: Túneles a través de Cloudflare Zero Trust con bloqueo del acceso IP directo al servidor mediante Middleware.

2. Colas asíncronas y aislamiento de cómputos pesados (Celery + Redis)

La conversión de archivos multimedia y paquetes de oficina genera cargas máximas en la CPU y la RAM. Para evitar que el proceso de procesamiento de mensajes entrantes en Telegram se bloquee durante operaciones pesadas, se implementa un aislamiento estricto:

  • Delegación de tareas a Redis: Al seleccionar un formato, el gestor de Telegram registra la tarea en la base de datos con el estado PROCESSING y coloca la tarea en la cola tasks.execute_conversion a través de Celery.
  • Contenedor de trabajador aislado: La ejecución de las utilidades de conversión se realiza en un contenedor de Linux separado con su propio límite de tiempo de procesador y memoria.
  • Control de bloqueos y tiempos de espera (Timeouts): Las llamadas a utilidades externas están envueltas en un contexto asíncrono con un control estricto del tiempo (conversion_timeout_sec = 180). Si se excede el límite, el proceso se termina a la fuerza mediante proc.kill(), liberando recursos.
  • Fallback tolerante a fallos: Si el agente Redis no está disponible temporalmente, la tarea es interceptada automáticamente por el despachador asíncrono local y se ejecuta directamente sin interrumpir al usuario.

3. Canalización de motores de conversión especializados

Para cada tipo de datos, se utilizan utilidades y bibliotecas nativas altamente especializadas:

  • Documentos y hojas de cálculo (LibreOffice): Paquete de oficina sin interfaz gráfica (headless) (soffice --headless) para la renderización precisa de DOCX, XLSX, PPTX, RTF, ODT a formato PDF o archivos de texto.
  • Audio y video por streaming (FFmpeg): Transcodificación multihilo de códecs de video (H.264), códecs de audio (MP3, OGG Opus), extracción de pistas de audio, generación de GIF (filtro Lanczos) y recorte cuadrado (1:1) de mensajes de video de Telegram.
  • Procesamiento de PDF de alta velocidad (Poppler Utils): Utilidades pdftotext (extracción instantánea de texto formateado en UTF-8) y pdftoppm (renderización de PDF página por página en imágenes ráster sin la sobrecarga de LibreOffice).
  • Reconocimiento óptico de caracteres (Tesseract OCR): Extracción basada en redes neuronales de texto impreso a partir de escaneos y fotografías en más de 40 idiomas.
  • Gráficos ráster y vectoriales: Bibliotecas Pillow (incluyendo compatibilidad con los formatos HEIC y AVIF), CairoSVG para imágenes vectoriales y lottie para stickers animados de Telegram (.TGS).
  • Libros, subtítulos y fuentes: El motor Calibre (ebook-convert), el analizador de subtítulos pysubs2 (SRT, VTT, ASS, SSA) y el compilador de fuentes fonttools (compresión Brotli en WOFF2).

4. Protección preventiva de recursos (System Guard)

Para proteger el servidor de caídas debido a la falta de memoria (OOM Killer), se ha implementado el servicio de diagnóstico preventivo System Guard. Antes de aceptar un archivo para su procesamiento, el sistema verifica métricas clave del host:

  • Memoria RAM libre: Mínimo 500 MB de volumen libre (guard_min_free_ram_mb).
  • Espacio en disco: Mínimo 2 GB de espacio libre en el directorio /tmp (guard_min_free_disk_mb).
  • Cola de tareas: Limitación de la longitud de la cola de Celery (no más de 20 tareas en espera).

Cuando se superan los límites, el servicio activa temporalmente la protección (HTTP 503 / mensaje en el chat), evitando la sobrecarga del servidor y enviando una alerta instantánea a los administradores en Telegram.

5. Ciclo de vida de los archivos y seguridad (GDPR)

La arquitectura está diseñada bajo el modelo Zero-Data-Footprint:

  • Los archivos de los usuarios se cargan en un volumen protegido tmp/conversions/ con prefijos únicos basados en identificadores de tareas.
  • Los archivos permanecen accesibles estrictamente durante la sesión de trabajo: no más de 15 minutos (900 segundos).
  • El recolector de basura automático borra los archivos originales y preparados inmediatamente después de confirmar el envío exitoso al chat o al expirar el tiempo de espera de la sesión.
  • La base de datos PostgreSQL no almacena archivos binarios ni textos personales de documentos; en las tablas solo se registran metadatos técnicos anonimizados (formatos, tamaños en bytes, tiempo de ejecución, estados).

6. REST API universal para servicios web externos

El servicio fue diseñado originalmente como un backend multiplataforma. Junto con el bot, opera una interfaz de programación protegida completa para sitios web (por ejemplo, en Django) y bots de terceros:

  • GET /api/v1/formats: matriz JSON dinámica de las direcciones de conversión disponibles, sincronizada con la configuración de Google Sheets.
  • POST /api/v1/convert: punto de conexión universal que acepta multipart/form-data (archivo, formato de destino, ID del cliente externo) y devuelve un flujo de bytes listo para su descarga directa.
  • Autorización mediante tokens Bearer (WEBHOOK_REFRESH_TOKEN) con protección contra ataques de tiempo a través de secrets.compare_digest.

7. Panel de control y Observability (NiceGUI + AG Grid)

El monitoreo de los indicadores de negocio y el estado del sistema se ha trasladado a un panel de control Single-Page nativo basado en NiceGUI 2.x:

  • Tablas interactivas AG Grid (v32+) con filtros de casilla de verificación personalizados al estilo Excel (aggrid_filters.js).
  • Monitoreo de colas, retrasos de proveedores de API y ping de PostgreSQL / Redis en tiempo real.
  • Filtrado completo por fechas con integración fluida del panel de BI Metabase a través de tokens JWT firmados.