El servei All File Converter està dissenyat com un sistema SaaS distribuït i escalable basat en la pila asíncrona moderna de Python 3.12. L'arquitectura està dividida en capes independents: recepció d'esdeveniments de xarxa, orquestració de tasques, execució aïllada de processos binaris pesats i el circuit analític.

1. Pila tecnològica general i arquitectura del sistema

La plataforma es basa en principis d'alt rendiment (high-throughput), consum mínim de memòria i protecció contra fallades:

  • Telegram Bot Framework: Aiogram 3.13, que funciona en mode Webhook amb validació de tokens secrets i filtres personalitzats del cicle de vida dels missatges.
  • Passarel·la web i REST API: FastAPI basat en el servidor ASGI Uvicorn amb lliurament de fluxos binaris de manera asíncrona (FileResponse) i neteja en segon pla mitjançant BackgroundTasks.
  • Jerarquia de cues i memòria cau: Redis 7 (gestió de tasques de Celery, bloqueigs contra condicions de carrera, protecció contra força bruta, caché de sessions).
  • Executant en segon pla (Task Queue): Celery 5.4 amb un conjunt dedicat de treballadors en el contenidor aïllat converter_worker.
  • Base de dades: PostgreSQL 16 amb la capa ORM SQLAlchemy 2.0 (asyncpg), grup de connexions persistents (20+10 overflow) i reintent automàtic de transaccions fallides (@db_retry).
  • Circuit de xarxa: Tunnelling a través de Cloudflare Zero Trust amb blocatge d'accés IP directe al servidor mitjançant Middleware.

2. Cues asíncrones i aïllament de càlculs pesats (Celery + Redis)

La conversió de fitxers multimèdia i paquets d'ofimàtica genera pics de càrrega a la CPU i la RAM. Per tal que el procés de processament de missatges entrants a Telegram no quedi bloquejat durant operacions pesades, s'ha implementat un aïllament estricte:

  • Delegació de tasques a Redis: En seleccionar el format, el gestor de Telegram registra la tasca a la BD amb l'estat PROCESSING i posa la tasca a la cua tasks.execute_conversion a través de Celery.
  • Contenidor de treballador aïllat: L'execució d'utilitats de conversió té lloc en un contenidor Linux separat amb el seu propi límit de temps de processament i memòria.
  • Control de congelacions i temps d'espera (timeouts): Les crides a utilitats externes s'envolten en un context asíncron amb un control estricte del temps (conversion_timeout_sec = 180). Si se supera el límit, el procés es finalitza de manera forçada mitjançant proc.kill(), alliberant recursos.
  • Fallback tolerant a fallades: Davant la indisponibilitat temporal del broker Redis, la tasca és interceptada automàticament pel despatxador asíncron local i s'executa directament sense errors per a l'usuari.

3. Pipeline de motors de conversió especialitzats

Per a cada tipus de dada s'utilitzen utilitats natives i biblioteques altament especialitzades:

  • Documents i fulls de càlcul (LibreOffice): Paquet d'ofimàtica headless (soffice --headless) per a un renderitzatge precís de DOCX, XLSX, PPTX, RTF, ODT a format PDF o fitxers de text.
  • Àudio i vídeo en streaming (FFmpeg): Transcodificació multi-fil de còdecs de vídeo (H.264), còdecs d'àudio (MP3, OGG Opus), extracció de pistes de so, generació de GIF (filtre Lanczos) i retall quadrat (1:1) de missatges de vídeo de Telegram.
  • Processament de PDF d'alta velocitat (Poppler Utils): Utilitats pdftotext (extracció instantània de text formatat en UTF-8) i pdftoppm (renderitzatge pàgina per pàgina de PDF a imatges ràster sense sobrecàrrega de LibreOffice).
  • Reconeixement òptic de caràcters (Tesseract OCR): Extracció basada en xarxes neuronals de text imprès a partir d'escanejats i fotografies en més de 40 idiomes.
  • Gràfics ràsters i vectorials: Biblioteques Pillow (incloent-hi suport per als formats HEIC i AVIF), CairoSVG per a imatges vectorials i lottie per a adhesius animats de Telegram (.TGS).
  • Llibres, subtítols i tipus de lletra: Motor Calibre (ebook-convert), analitzador de subtítols pysubs2 (SRT, VTT, ASS, SSA) i compilador de tipus de lletra fonttools (compressió Brotli a WOFF2).

4. Protecció preventiva de recursos (System Guard)

Per protegir el servidor de caigudes a causa de la manca de memòria (OOM Killer), s'ha integrat el servei de diagnòstic preventiu System Guard. Abans d'acceptar un fitxer per al seu processament, el sistema comprova les mètriques clau de l'amfitrió:

  • Memòria RAM lliure: Mínim 500 MB d'espai lliure (guard_min_free_ram_mb).
  • Espai en disc: Mínim 2 GB d'espai lliure al directori /tmp (guard_min_free_disk_mb).
  • Cua de tasques: Límits en la longitud de la cua de Celery (no més de 20 tasques en espera).

En superar els límits, el servei activa temporalment la protecció (HTTP 503 / missatge al xat), evitant la sobrecàrrega del servidor i enviant una alerta instantània als administradors a Telegram.

5. Cicle de vida dels fitxers i seguretat (GDPR)

L'arquitectura està dissenyada segons el model Zero-Data-Footprint:

  • Els fitxers dels usuaris es pengen a un volum protegit tmp/conversions/ amb prefixos únics basats en els identificadors de les tasques.
  • Els fitxers romanen accessibles estrictament dins del marc de la sessió de treball — no més de 15 minuts (900 segons).
  • El recol·lector d'escombraries automàtic esborra els fitxers originals i preparats immediatament després de confirmar l'enviament correcte al xat o un cop expirat el temps d'espera de la sessió.
  • La base de dades PostgreSQL no emmagatzema fitxers binaris ni textos personals de documents; a les taules només s'hi registren metadades tècniques anonimitzades (formats, mides en bytes, temps de funcionament, estats).

6. REST API universal per a serveis web externs

El servei està dissenyat des del principi com un backend multiplataforma. Juntament amb el bot, funciona una interfície de programació protegida completa per a llocs web (per exemple, basats en Django) i bots de tercers:

  • GET /api/v1/formats — matriu JSON dinàmica de les adreces de conversió disponibles, sincronitzada amb la configuració de Google Sheets.
  • POST /api/v1/convert — punt d'entrada universal que accepta multipart/form-data (fitxer, format de destinació, ID de client extern) i retorna el flux de bytes preparat en forma de descàrrega directa.
  • Autorització mitjançant Bearer tokens (WEBHOOK_REFRESH_TOKEN) amb protecció contra atacs de temporització a través de secrets.compare_digest.

7. Panell de control i Observability (NiceGUI + AG Grid)

La monitorització de les mètriques de negoci i de l'estat del sistema s'ha traslladat a un panell de control Single-Page natiu basat en NiceGUI 2.x:

  • Taules interactives AG Grid (v32+) amb filtres personalitzats d'estil Excel (aggrid_filters.js).
  • Monitorització en temps real de cues, latències de proveïdors d'API i ping de PostgreSQL / Redis.
  • Filtratge transversal per dates amb integració transparent del tauler de BI Metabase mitjançant JWT tokens signats.