O servizo All File Converter está deseñado como un sistema SaaS distribuído e escaleirable baseado no moderno stack asíncrono de Python 3.12. A arquitectura está dividida en capas independentes: recepción de eventos de rede, orquestración de tarefas, execución illada de procesos binarios pesados e o circuíto analítico.

1. Stack tecnolóxico xeral e arquitectura do sistema

A plataforma baséase en principios de alto rendemento (high-throughput), consumo mínimo de memoria e protección contra fallos:

  • Telegram Bot Framework: Aiogram 3.13, que funciona en modo Webhook con validación de tokens secretos e filtros personalizados do ciclo de vida das mensaxes.
  • Pasarela web e REST API: FastAPI baseado no servidor ASGI Uvicorn con entrega de fluxo asíncrono de ficheiros binarios (FileResponse) e limpeza en segundo plano mediante BackgroundTasks.
  • Agente de colas e caché: Redis 7 (xestión de tarefas de Celery, bloqueos fronte a condicións de carreira, protección contra forza bruta, caché de sesións).
  • Executor en segundo plano (Task Queue): Celery 5.4 cun grupo dedicado de traballadores nun contedor illado converter_worker.
  • Base de datos: PostgreSQL 16 coa capa ORM SQLAlchemy 2.0 (asyncpg), grupo de conexións persistentes (20+10 overflow) e reintento automático de transaccións con fallos (@db_retry).
  • Circuíto de rede: Tunelización a través de Cloudflare Zero Trust coa bloqueo do acceso IP directo ao servidor mediante Middleware.

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

A conversión de ficheiros multimedia e paquetes de oficina xera cargas punta de CPU e RAM. Para evitar que o proceso de tratamento de mensaxes entrantes en Telegram se bloquee durante operacións pesadas, impleméntase un estrito illamento:

  • Delegación de tarefas en Redis: Ao seleccionar un formato, o xestor de Telegram rexistra a tarefa na base de datos co estado PROCESSING e coloca a tarefa na cola tasks.execute_conversion a través de Celery.
  • Contedor de traballador illado: A execución das utilidades de conversión ten lugar nun contedor de Linux separado co seu propio límite de tempo de procesador e memoria.
  • Control de conxelacións e tempos de espera: As chamadas a utilidades externas están envoltas nun contexto asundo cun estrito control do tempo (conversion_timeout_sec = 180). Se se supera o límite, o proceso remátase á forza mediante proc.kill(), liberando recursos.
  • Fallback tolerante a fallos: Se o intermediario Redis non está dispoñible temporalmente, a tarefa é interceptada automaticamente polo xestor asíncrono local e executada directamente sen fallos para o usuario.

3. Tubaxe de motores de conversión especializados

Para cada tipo de datos utilízanse utilidades e bibliotecas nativas altamente especializadas:

  • Documentos e follas de cálculo (LibreOffice): Paquete de oficina sen cabeza (soffice --headless) para a renderización precisa de DOCX, XLSX, PPTX, RTF, ODT a formato PDF ou ficheiros de texto.
  • Audio e vídeo en streaming (FFmpeg): Transcodificación multiobra de códecs de vídeo (H.264), códecs de audio (MP3, OGG Opus), extracción de pistas de son, xeración de GIF (filtro Lanczos) e recorte cadrado (1:1) de mensaxes de vídeo de Telegram.
  • Procesamento de alta velocidade de PDF (Poppler Utils): Utilidades pdftotext (extracción instantánea de texto formatado en UTF-8) e pdftoppm (renderización páxina por páxina de PDF en imaxes ráster sen custos xerais de LibreOffice).
  • Recoñecemento óptico de caracteres (Tesseract OCR): Extracción mediante redes neuronais de texto impreso de escaneos e fotos en máis de 40 idiomas.
  • Gráficos ráster e vectoriais: Bibliotecas Pillow (incluíndo soporte para formatos HEIC e AVIF), CairoSVG para imaxes vectoriais e lottie para adhesivos animados de Telegram (.TGS).
  • Libros, subtítulos e fontes: Motor Calibre (ebook-convert), analizador de subtítulos pysubs2 (SRT, VTT, ASS, SSA) e compilador de fontes fonttools (compresión Brotli en WOFF2).

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

Para protexer o servidor contra caídas debido á escaseza de memoria (OOM Killer), implementouse o servizo de diagnose preventiva System Guard. Antes de aceptar un ficheiro para o seu procesamento, o sistema comproba as métricas clave do host:

  • Memoria RAM dispoñible: Un mínimo de 500 MB de volume libre (guard_min_free_ram_mb).
  • Espazo en disco: Un mínimo de 2 GB de espazo libre no directorio /tmp (guard_min_free_disk_mb).
  • Cola de tarefas: Limitación da lonxitude da cola de Celery (non máis de 20 tarefas pendentes).

Se se superan os límites, o servizo activa temporalmente a protección (HTTP 503 / mensaxe no chat), evitando a sobrecarga do servidor e enviando unha alerta instantánea aos administradores en Telegram.

5. Ciclo de vida dos ficheiros e seguridade (GDPR)

A arquitectura está deseñada segundo o modelo Zero-Data-Footprint:

  • Os ficheiros dos usuarios cárganse nun volume seguro tmp/conversions/ con prefixos únicos baseados en identificadores de tarefas.
  • Os ficheiros permanecen dispoñibles estrictamente dentro da sesión de traballo — non máis de 15 minutos (900 segundos).
  • O recolector de lixo automático elimina os ficheiros orixinais e preparados inmediatamente despois de confirmar o envío exitoso ao chat ou cando remata o tempo de espera da sesión.
  • A base de datos PostgreSQL non almacena ficheiros binarios nin textos persoais de documentos; nas táboas só se rexistran metadatos técnicos anonimizados (formatos, tamaños en bytes, tempo de funcionamento, estados).

6. REST API universal para servizos web externos

O servizo foi deseñado orixinalmente como un backend multiplataforma. Xunto co bot, opera unha interface de programación segura e completa para sitios web (por exemplo, en Django) e bots de terceiros:

  • GET /api/v1/formats — matriz JSON dinámica de direccións de conversión dispoñibles, sincronizada coa configuración de Google Sheets.
  • POST /api/v1/convert — punto de acceso universal que acepta multipart/form-data (ficheiro, formato de destino, ID de cliente externo) e devolve un fluxo de bytes listo en forma de descarga directa.
  • Autorización mediante Bearer tokens (WEBHOOK_REFRESH_TOKEN) con protección contra ataques temporais a través de secrets.compare_digest.

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

O seguimento dos indicadores de negocio e do estado do sistema trasladouse a un panel de control Single-Page nativo baseado en NiceGUI 2.x:

  • Táboas interactivas AG Grid (v32+) con filtros de caixa de verificación personalizados ao estilo Excel (aggrid_filters.js).
  • Supervisión en tempo real de colas, atrasos de provedores de API e ping de PostgreSQL / Redis.
  • Filtrado transversal por datas cunha integración sen fisuras do panel BI Metabase mediante tokens JWT asinados.