Serviciul All File Converter este proiectat ca un sistem SaaS distribuit și scalabil, bazat pe stiva modernă asincronă Python 3.12. Arhitectura este împărțită în niveluri independente: recepționarea evenimentelor de rețea, orchestrarea sarcinilor, execuția izolată a proceselor binare grele și conturul analitic.

1. Stiva generală de tehnologii și arhitectura de sistem

Platforma se bazează pe principii de performanță ridicată (high-throughput), consum minim de memorie și protecție împotriva erorilor:

  • Telegram Bot Framework: Aiogram 3.13, care rulează în modul Webhook cu validarea tokenurilor secrete și filtre personalizate pentru ciclul de viață al mesajelor.
  • Gateway web și REST API: FastAPI bazat pe serverul ASGI Uvicorn cu livrare asincronă în flux a fișierelor binare (FileResponse) și curățare în fundal prin BackgroundTasks.
  • Broker de cozi și cache: Redis 7 (gestionarea sarcinilor Celery, blocări împotriva stării de curse, protecție împotriva atacurilor de tip brute-force, stocare în cache a sesiunilor).
  • Executor în fundal (Task Queue): Celery 5.4 cu un grup dedicat de workeri într-un container izolat converter_worker.
  • Bază de date: PostgreSQL 16 cu nivelul ORM SQLAlchemy 2.0 (asyncpg), pool de conexiuni permanente (20+10 overflow) și reîncercare automată pentru tranzacțiile eșuate (@db_retry).
  • Contur de rețea: Tunelare prin Cloudflare Zero Trust cu blocarea accesului IP direct la server prin Middleware.

2. Cozi asincrone și izolare a calculelor grele (Celery + Redis)

Conversia fișierelor multimedia și a pachetelor de birou creează sarcini de vârf pe CPU și RAM. Pentru ca procesul de procesare a mesajelor primite în Telegram să nu fie blocat în timpul operațiunilor grele, s-a implementat o izolare strictă:

  • Delegarea sarcinilor către Redis: La selectarea formatului, handlerul Telegram înregistrează sarcina în BD cu starea PROCESSING și plasează sarcina în coada tasks.execute_conversion prin Celery.
  • Container worker izolat: Executarea utilitarelor de conversie are loc într-un container Linux separat, cu propria limită de timp de procesor și memorie.
  • Controlul blocajelor și timeout-uri: Apelurile către utilitare externe sunt încapsulate într-un context asincron cu control strict al timpului (conversion_timeout_sec = 180). La depășirea limitei, procesul este oprit forțat prin proc.kill(), eliberând resursele.
  • Fallback rezistent la erori: În cazul indisponibilității temporare a brokerului Redis, sarcina este preluată automat de dispatcherul asincron local și executată direct, fără întreruperi pentru utilizator.

3. Pipeline de motoare de conversie specializate

Pentru fiecare tip de date sunt utilizate utilitare și biblioteci native extrem de specializate:

  • Documente și tabele (LibreOffice): Pachet de birou fără cap (soffice --headless) pentru randarea precisă a fișierelor DOCX, XLSX, PPTX, RTF, ODT în format PDF sau fișiere text.
  • Audio și video în flux (FFmpeg): Transcodare multithread a codecivelor video (H.264), audio (MP3, OGG Opus), extragerea pistelor audio, generarea GIF (filtru Lanczos) și decuparea pătrată (1:1) a mesajelor video Telegram.
  • Procesare PDF de mare viteză (Poppler Utils): Utilitarele pdftotext (extragere instantanee a textului formatat în UTF-8) și pdftoppm (randare pagină cu pagină a PDF-urilor în imagini raster, fără costuri suplimentare din partea LibreOffice).
  • Recunoaștere optică (Tesseract OCR): Extragerea prin rețele neuronale a textului tipărit din scanări și fotografii în peste 40 de limbi.
  • Grafică raster și vectorială: Bibliotecile Pillow (inclusiv suport pentru formatele HEIC și AVIF), CairoSVG pentru imagini vectoriale și lottie pentru stickere animate Telegram (.TGS).
  • Cărți, subtitrări și fonturi: Motorul Calibre (ebook-convert), parserul de subtitrări pysubs2 (SRT, VTT, ASS, SSA) și compilerul de fonturi fonttools (compresie Brotli în WOFF2).

4. Protecție preventivă a resurselor (System Guard)

Pentru a proteja serverul împotriva căderilor din cauza lipsei de memorie (OOM Killer), a fost implementat serviciul de diagnosticare preventivă System Guard. Înainte de a prelua un fișier spre procesare, sistemul verifică metricile cheie ale gazdei:

  • Memorie RAM liberă: Un minim de 500 MB volum liber (guard_min_free_ram_mb).
  • Spațiu pe disc: Un minim de 2 GB spațiu liber în directorul /tmp (guard_min_free_disk_mb).
  • Coada de sarcini: Limitarea lungimii cozii Celery (maximum 20 de sarcini în așteptare).

La depășirea limitelor, serviciul activează temporar protecția (HTTP 503 / mesaj în chat), prevenind suprasolicitarea serverului și trimițând o alertă instantanee administratorilor pe Telegram.

5. Ciclul de viață al fișierelor și securitatea (GDPR)

Arhitectura este proiectată conform modelului Zero-Data-Footprint:

  • Fișierele utilizatorilor sunt încărcate într-un volum securizat tmp/conversions/ cu prefixe unice bazate pe identificatorii sarcinilor.
  • Fișierele rămân disponibile strict în cadrul sesiunii de lucru — cel mult 15 minute (900 secunde).
  • Colectorul automat de gunoi șterge fișierele originale și cele gata imediat după confirmarea trimiterii cu succes în chat sau la expirarea timpului de sesiune.
  • Baza de date PostgreSQL nu stochează fișiere binare sau texte personale ale documentelor — tabelele înregistrează doar metadate tehnice anonimizate (formate, dimensiuni în octeți, timp de lucru, stări).

6. REST API universal pentru servicii web externe

Serviciul este conceput din start ca un backend multiplataفرم (multiplatformă). Alături de bot, funcționează o interfață de programare securizată completă pentru site-uri web (de exemplu, pe Django) și boți terți:

  • GET /api/v1/formats — matrice JSON dinamică a direcțiilor de conversie disponibile, sincronizată cu setările Google Sheets.
  • POST /api/v1/convert — endpoint universal care acceptă multipart/form-data (fișier, format țintă, ID client extern) și returnează un flux gata de octeți sub formă de descărcare directă.
  • Autorizare prin tokenuri Bearer (WEBHOOK_REFRESH_TOKEN) cu protecție împotriva atacurilor de sincronizare prin secrets.compare_digest.

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

Monitorizarea indicatorilor de afaceri și a stării sistemului a fost mutată într-un panou de control nativ Single-Page bazat pe NiceGUI 2.x:

  • Tabele interactive AG Grid (v32+) cu filtre personalizate tip Excel pentru căsuțe de selectare (aggrid_filters.js).
  • Monitorizarea în timp real a cozilor, întârzierilor furnizorilor API și a ping-ului PostgreSQL / Redis.
  • Filtrare transversală după date cu integrare perfectă a tabloului de bord BI Metabase prin tokenuri JWT semnate.