Il servizio All File Converter è progettato come un sistema SaaS distribuito e scalabile basato su uno stack asincrono moderno Python 3.12. L'architettura è suddivisa in livelli indipendenti: ricezione degli eventi di rete, orchestrazione delle attività, esecuzione isolata di processi binari pesanti e circuito analitico.

1. Stack tecnologico generale e architettura di sistema

La piattaforma si basa sui principi di alte prestazioni (high-throughput), consumo minimo di memoria e protezione dai guasti:

  • Telegram Bot Framework: Aiogram 3.13, funzionante in modalità Webhook con validazione dei token segreti e filtri personalizzati del ciclo di vita dei messaggi.
  • Gateway Web e REST API: FastAPI basato sul server ASGI Uvicorn con invio asincrono in streaming di file binari (FileResponse) e pulizia in background tramite BackgroundTasks.
  • Broker di code e cache: Redis 7 (gestione delle attività Celery, blocchi contro le condizioni di gara, protezione da brute force, caching delle sessioni).
  • Esecutore in background (Task Queue): Celery 5.4 con un pool dedicato di worker in un contenitore isolato converter_worker.
  • Database: PostgreSQL 16 con livello ORM SQLAlchemy 2.0 (asyncpg), pool di connessioni persistenti (20+10 overflow) e ripetizione automatica delle transazioni fallite (@db_retry).
  • Circuito di rete: Tunneling tramite Cloudflare Zero Trust con blocco dell'accesso IP diretto al server tramite Middleware.

2. Code asincrone e isolamento dei calcoli pesanti (Celery + Redis)

La conversione di file multimediali e pacchetti office genera carichi di picco su CPU e RAM. Affinché il processo di elaborazione dei messaggi in arrivo su Telegram non venga bloccato durante le operazioni pesanti, viene implementato un rigoroso isolamento:

  • Delega delle attività a Redis: Al momento della selezione del formato, il gestore di Telegram registra l'attività nel DB con lo stato PROCESSING e inserisce l'incarico nella coda tasks.execute_conversion tramite Celery.
  • Contenitore worker isolato: L'esecuzione delle utilità di conversione avviene in un contenitore Linux separato con un proprio limite di tempo di elaborazione e memoria.
  • Controllo dei blocchi e timeout: Le chiamate a utilità esterne sono racchiuse in un contesto asincrono con un rigido controllo del tempo (conversion_timeout_sec = 180). In caso di superamento del limite, il processo viene terminato forzatamente tramite proc.kill(), liberando le risorse.
  • Fallback a tolleranza d'errore: In caso di temporanea indisponibilità del broker Redis, l'attività viene intercettata automaticamente dal dispatcher asincrono locale ed eseguita direttamente senza interruzioni per l'utente.

3. Pipeline di motori di conversione specializzati

Per ogni tipo di dato vengono utilizzate utilità e librerie native altamente specializzate:

  • Documenti e fogli di calcolo (LibreOffice): Pacchetto office headless (soffice --headless) per il rendering accurato di DOCX, XLSX, PPTX, RTF, ODT in formato PDF o file di testo.
  • Audio e video in streaming (FFmpeg): Transcodifica multithread di codec video (H.264), codec audio (MP3, OGG Opus), estrazione di tracce audio, generazione di GIF (filtro Lanczos) e ritaglio quadrato (1:1) dei messaggi video di Telegram.
  • Elaborazione PDF ad alta velocità (Poppler Utils): Utilità pdftotext (estrazione istantanea di testo formattato in UTF-8) e pdftoppm (rendering pagina per pagina di PDF in immagini raster senza i costi generali di LibreOffice).
  • Riconoscimento ottico (Tesseract OCR): Estrazione tramite reti neurali di testo stampato da scansioni e foto in oltre 40 lingue.
  • Grafica raster e vettoriale: Librerie Pillow (inclusi il supporto per i formati HEIC e AVIF), CairoSVG per immagini vettoriali e lottie per sticker animati di Telegram (.TGS).
  • Libri, sottotitoli e font: Motore Calibre (ebook-convert), parser di sottotitoli pysubs2 (SRT, VTT, ASS, SSA) e compilatore di font fonttools (compressione Brotli in WOFF2).

4. Protezione preventiva delle risorse (System Guard)

Per proteggere il server da arresti anomali dovuti a esaurimento della memoria (OOM Killer), è stato introdotto il servizio di diagnostica preventiva System Guard. Prima di accettare un file per l'elaborazione, il sistema verifica le metriche chiave dell'host:

  • Memoria RAM libera: Minimo 500 MB di spazio libero (guard_min_free_ram_mb).
  • Spazio su disco: Minimo 2 GB di spazio libero nella directory /tmp (guard_min_free_disk_mb).
  • Coda delle attività: Limitazione della lunghezza della coda Celery (non più di 20 attività in attesa).

Se i limiti vengono superati, il servizio attiva temporaneamente la protezione (HTTP 503 / messaggio in chat), prevenendo il sovraccarico del server e inviando un avviso immediato agli amministratori su Telegram.

5. Ciclo di vita dei file e sicurezza (GDPR)

L'architettura è progettata secondo il modello Zero-Data-Footprint:

  • I file degli utenti vengono caricati in un volume protetto tmp/conversions/ con prefissi univoci basati sugli identificatori delle attività.
  • I file rimangono accessibili rigorosamente nell'ambito della sessione di lavoro — per non più di 15 minuti (900 secondi).
  • Il garbage collector automatico cancella i file originali e pronti immediatamente dopo la conferma dell'invio riuscito in chat o allo scadere del timeout della sessione.
  • Il database PostgreSQL non memorizza file binari o testi personali di documenti: nelle tabelle vengono registrati solo metadati tecnici anonimizzati (formati, dimensioni in byte, tempo di elaborazione, stati).

6. REST API universale per servizi Web esterni

Il servizio è stato progettato fin dall'inizio come backend multi-piattaforma. Insieme al bot, funziona un'interfaccia di programmazione protetta a tutti gli effetti per siti Web (ad esempio su Django) e bot di terze parti:

  • GET /api/v1/formats — matrice JSON dinamica delle direzioni di conversione disponibili, sincronizzata con le impostazioni di Google Fogli.
  • POST /api/v1/convert — endpoint universale che accetta multipart/form-data (file, formato di destinazione, ID del client esterno) e restituisce un flusso di byte pronto sotto forma di download diretto.
  • Autenticazione tramite Bearer token (WEBHOOK_REFRESH_TOKEN) con protezione dagli attacchi di tipo timing tramite secrets.compare_digest.

7. Pannello di controllo e Observability (NiceGUI + AG Grid)

Il monitoraggio delle metriche aziendali e dello stato del sistema è stato integrato in un pannello di controllo Single-Page nativo basato su NiceGUI 2.x:

  • Tabelle interattive AG Grid (v32+) con filtri checkbox personalizzati in stile Excel (aggrid_filters.js).
  • Monitoraggio in tempo reale delle code, dei ritardi dei provider API e del ping di PostgreSQL / Redis.
  • Filtro end-to-end per date con integrazione trasparente del dashboard BI Metabase tramite token JWT firmati.