Služba All File Converter je navrhnutá ako škálovateľný distribuovaný SaaS systém založený na modernom asynchrónnom zásobníku Python 3.12. Architektúra je rozdelená na nezávislé vrstvy: príjem sieťových udalostí, orchestrácia úloh, izolované spúšťanie ťažkých binárnych procesov a analytický okruh.

1. Celkový technologický stack a systémová architektúra

Základom platformy sú princípy vysokej priepustnosti (high-throughput), minimálnej spotreby pamäte a ochrany proti zlyhaniam:

  • Telegram Bot Framework: Aiogram 3.13, pracujúci v režime Webhook s validáciou tajných tokenov a vlastnými filtrami životného cyklu správ.
  • Webová brána a REST API: FastAPI na báze ASGI servera Uvicorn s asynchrónnym streamovaním binárnych súborov (FileResponse) a pozadovým čistením cez BackgroundTasks.
  • Broker poradí a vyrovnávacia pamäť: Redis 7 (správa úloh Celery, zámky proti stavu pretečenia, ochrana proti brute force, cachovanie relácií).
  • Pozadový exekútor (Task Queue): Celery 5.4 s vyhradeným poolom workerov v izolovanom kontajneri converter_worker.
  • Databáza: PostgreSQL 16 s ORM vrstvou SQLAlchemy 2.0 (asyncpg), poolom trvalých pripojení (20+10 overflow) a automatickým opakovaním chybných transakcií (@db_retry).
  • Sieťový okruh: Tunelovanie cez Cloudflare Zero Trust s blokovaním priameho IP prístupu k serveru cez Middleware.

2. Asynchrónne poradia a izolácia náročných výpočtov (Celery + Redis)

Konverzia multimediálnych súborov a kancelárskych balíkov vytvára špičkové zaťaženie CPU a RAM. Aby proces spracovania prichádzajúcich správ v Telegrame nebol blokovaný pri náročných operáciách, je implementovaná prísna izolácia:

  • Delegovanie úloh do Redis: Pri výbere formátu Telegram handler zaregistruje úlohu v DB so stavom PROCESSING a zaradí úlohu do poradí tasks.execute_conversion cez Celery.
  • Izolovaný kontajner workera: Vykonávanie konverzných utilít prebieha v samostatnom Linux kontajneri s vlastným limitom procesorového času a pamäte.
  • Kontrola zablokovaní a timeouty: Volania externých utilít sú obalené do asynchrónneho kontextu s prísnou kontrolou času (conversion_timeout_sec = 180). Pri prekročení limitu sa proces násilne ukončí cez proc.kill(), čím sa uvoľnia zdroje.
  • Tolerantný Fallback: Pri dočasnej nedostupnosti brokera Redis je úloha automaticky zachytená lokálnym asynchrónnym dispečerom a vykonaná priamo bez výpadku pre používateľa.

3. Pipeline špecializovaných konverzných nástrojov

Pre každý typ údajov sa používajú špecializované natívne utility a knižnice:

  • Dokumenty a tabuľky (LibreOffice): Bezhlavý kancelársky balík (soffice --headless) na presný rendering DOCX, XLSX, PPTX, RTF, ODT do formátu PDF alebo textových súborov.
  • Streamované audio a video (FFmpeg): Viacvláknové prekonódovanie videokodekov (H.264), audiokodekov (MP3, OGG Opus), extrakcia zvukových stop, generovanie GIF (Lanczos filter) a štvorcové orezanie (1:1) video správ Telegramu.
  • Vysokorýchlostné spracovanie PDF (Poppler Utils): Utility pdftotext (okamžitá extrakcia formátovaného textu do UTF-8) a pdftoppm (stránkový rendering PDF do rastrových obrázkov bez réžie LibreOffice).
  • Optické rozpoznávanie (Tesseract OCR): Neurónové sieťové extrahovanie tlačeného textu zo skenov a fotografií vo viac ako 40 jazykoch.
  • Rastrová a vektoriálna grafika: Knižnice Pillow (vrátane podpory formátov HEIC a AVIF), CairoSVG pre vektorové obrázky a lottie pre animované nálepky Telegramu (.TGS).
  • Knihy, titulky a fonty: Engine Calibre (ebook-convert), parser titulkov pysubs2 (SRT, VTT, ASS, SSA) a kompilátor fontov fonttools (Brotli kompresia do WOFF2).

4. Preventívna ochrana zdrojov (System Guard)

Na ochranu pred pádom servera v dôsledku nedostatku pamäte (OOM Killer) je integrovaná služba preventívnej diagnostiky System Guard. Pred prijatím súboru na spracovanie systém skontroluje kľúčové metriky hostiteľa:

  • Voľná operačná pamäť (RAM): Minimálne 500 MB voľného objemu (guard_min_free_ram_mb).
  • Miesto na disku: Minimálne 2 GB voľného priestoru v adresári /tmp (guard_min_free_disk_mb).
  • Fronta úloh: Obmedzenie dĺžky frontu Celery (nie viac ako 20 čakajúcich úloh).

Pri prekročení limitov služba dočasne zapne ochranu (HTTP 503 / správa v chate), čím zabráni preťaženiu servera a odošle okamžitý alert administrátorom v Telegrame.

5. Životný cyklus súborov a bezpečnosť (GDPR)

Architektúra je navrhnutá podľa modelu Zero-Data-Footprint:

  • Používateľské súbory sa nahrajú do chráneného zväzku tmp/conversions/ s unikátnymi predponami na základe identifikátorov úloh.
  • Súbory zostávajú dostupné striktne v rámci pracovnej relácie — nie viac ako 15 minút (900 sekúnd).
  • Automatický zberateľ odpadu vymaže zdrojové a pripravené súbory ihneď po potvrdení úspešného odoslania do chat alebo po uplynutí časového limitu relácie.
  • Databáza PostgreSQL neukladá binárne súbory ani osobné texty dokumentov — v tabuľkách sa fixujú iba anonymizované technické metadáta (formáty, veľkosti v bajtoch, čas práce, stavy).

6. Univerzálne REST API pre externé webové služby

Služba je od začiatku navrhnutá ako multiplatformový backend. Popri bote funguje plnohodnotné chránené programové rozhranie pre webové stránky (napríklad na Django) a externých botov:

  • GET /api/v1/formats — dynamická JSON matrica dostupných smerov konverzie, synchronizovaná s nastaveniami Google Tabuliek.
  • POST /api/v1/convert — univerzálny endpoint, prijímajúci multipart/form-data (súbor, cieľový formát, ID externého klienta) a vydávajúci pripravený prúd bajtov vo forme priameho sťahovania.
  • Autorizácia cez Bearer tokeny (WEBHOOK_REFRESH_TOKEN) s ochranou proti útokom na základe času cez secrets.compare_digest.

7. Ovládací panel a Observability (NiceGUI + AG Grid)

Monitorovanie obchodných ukazovateľov a stavu systému je vyvedené do natívneho Single-Page ovládacieho panela na báze NiceGUI 2.x:

  • Interaktívne tabuľky AG Grid (v32+) s vlastnými Excel-style checkbox filtrami (aggrid_filters.js).
  • Monitorovanie front, omeškaní API providerov a pingu PostgreSQL / Redis v reálnom čase.
  • Priebežné filtrovanie podľa dátumov s bezproblémovou integráciou BI dashboardu Metabase cez podpísané JWT tokeny.