Služba All File Converter je navržena jako škálovatelný distribuovaný SaaS systém založený na moderním asynchronním stacku Python 3.12. Architektura je rozdělena na nezávislé vrstvy: příjem síťových událostí, orchestrace úloh, izolované spouštění náročných binárních procesů a analytický okruh.

1. Celkový technologický stack a systémová architektura

Základem platformy jsou principy vysoké propustnosti (high-throughput), minimální spotřeby paměti a ochrany proti výpadkům:

  • Telegram Bot Framework: Aiogram 3.13, běžící v režimu Webhook s ověřováním tajných tokenů a vlastními filtry životního cyklu zpráv.
  • Webová brána a REST API: FastAPI na bázi ASGI serveru Uvicorn s asynchronním streamováním binárních souborů (FileResponse) a čištěním na pozadí přes BackgroundTasks.
  • Zprostředkovatel front a cache: Redis 7 (správa úloh Celery, zámky proti race condition, ochrana proti brute-force, cachování relací).
  • Spouštěč úloh na pozadí (Task Queue): Celery 5.4 s vyhrazeným poolem workerů v izolovaném kontejneru converter_worker.
  • Databáze: PostgreSQL 16 s ORM vrstvou SQLAlchemy 2.0 (asyncpg), poolem stálých připojení (20+10 overflow) a automatickým opakováním chybových transakcí (@db_retry).
  • Síťový okruh: Tunelování přes Cloudflare Zero Trust s blokováním přímého IP přístupu k serveru přes Middleware.

2. Asynchronní fronty a izolace náročných výpočtů (Celery + Redis)

Konverze multimediálních souborů a kancelářských balíků vytváří špičkové zatížení CPU a RAM. Aby nedocházelo k blokování zpracování příchozích zpráv v Telegram při náročných operacích, je implementována přísná izolace:

  • Delegování úloh do Redis: Při výběru formátu zaregistruje obslužná rutina Telegram úlohu v DB se stavem PROCESSING a zařadí úkol do fronty tasks.execute_conversion přes Celery.
  • Izolovaný kontejner workera: Spouštění konverzních utilit probíhá v samostatném Linux kontejneru s vlastním limitem procesorového času a paměti.
  • Kontrola zablokování a timeouty: Volání externích utilit jsou zabalena do asynchronního kontextu s přísnou kontrolou času (conversion_timeout_sec = 180). Při překročení limitu je proces násilně ukončen přes proc.kill(), čímž se uvolní zdroje.
  • Odolný Fallback: Při dočasné nedostupnosti zprostředkovatele Redis je úloha automaticky zachycena lokálním asynchronním dispečerem a provedena přímo bez výpadku pro uživatele.

3. Pipeline specializovaných konverzních engine

Pro každý typ dat se používají vysoce specializované nativní utility a knihovny:

  • Dokumenty a tabulky (LibreOffice): Headless kancelářský balík (soffice --headless) pro přesný rendering DOCX, XLSX, PPTX, RTF, ODT do formátu PDF nebo textových souborů.
  • Streamované audio a video (FFmpeg): Vícevláknové převedení videokodeků (H.264), audiokodeků (MP3, OGG Opus), extrakce zvukových stop, generování GIF (Lanczos filtr) a čtvercové ořezávání (1:1) videozpráv Telegram.
  • Vysokorychlostní zpracování PDF (Poppler Utils): Utility pdftotext (okamžitá extrakce formátovaného textu v UTF-8) a pdftoppm (stránkový rendering PDF do rastrových obrázků bez režie LibreOffice).
  • Optické rozpoznávání (Tesseract OCR): Neurokursová extrakce tištěného textu ze skenů a fotografií ve 40+ jazycích.
  • Rastrová a vektorová grafika: Knihovny Pillow (včetně podpory formátů HEIC a AVIF), CairoSVG pro vektorové obrázky a lottie pro animované nálepky Telegram (.TGS).
  • Knihy, titulky a fonty: Engine Calibre (ebook-convert), parser titulků pysubs2 (SRT, VTT, ASS, SSA) a kompilátor fontů fonttools (Brotli komprese ve WOFF2).

4. Preventivní ochrana zdrojů (System Guard)

Pro ochranu před pádem serveru z důvodu nedostatku paměti (OOM Killer) je implementována služba preventivní diagnostiky System Guard. Před přijetím souboru ke zpracování systém kontroluje klíčové metriky hostitele:

  • Volná operační paměť (RAM): Minimum 500 MB volného objemu (guard_min_free_ram_mb).
  • Místo na disku: Minimum 2 GB volného prostoru v adresáři /tmp (guard_min_free_disk_mb).
  • Fronta úloh: Omezení délky fronty Celery (maximálně 20 čekajících úloh).

Při překročení limitů služba dočasně zapne ochranu (HTTP 503 / zpráva v chatu), čímž zabrání přetížení serveru a odešle okamžitý alert administrátorům v Telegram.

5. Životní cyklus souborů a bezpečnost (GDPR)

Architektura je navržena podle modelu Zero-Data-Footprint:

  • Uživatelské soubory se nahrávají do zabezpečeného svazku tmp/conversions/ s unikátními prefixy na základě identifikátorů úloh.
  • Soubory zůstávají dostupné striktně v rámci pracovní relace — maximálně 15 minut (900 sekund).
  • Automatický garbage collector vymaže původní a hotové soubory ihned po potvrzení úspěšného odeslání do chatu nebo po vypršení timeoutu relace.
  • Databáze PostgreSQL neukládá binární soubory ani osobní texty dokumentů — v tabulkách se zaznamenávají pouze anonymizovaná technická metadata (formáty, velikosti v bytech, doba běhu, stavy).

6. Univerzální REST API pro externí webové služby

Služba je od počátku navržena jako multiplatformní backend. Souběžně s botem funguje plnohodnotné zabezpečené programové rozhraní pro weby (například v Django) a externí boty:

  • GET /api/v1/formats — dynamická JSON matice dostupných směrů konverze, synchronizovaná s nastavením Google Tabulek.
  • POST /api/v1/convert — univerzální endpoint, který přijímá multipart/form-data (soubor, cílový formát, ID externího klienta) a vrací připravený proud bajtů ve formě přímého stahování.
  • Autorizace pomocí Bearer tokenů (WEBHOOK_REFRESH_TOKEN) s ochranou proti útokům načasování přes secrets.compare_digest.

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

Monitoring podnikových metrik a stavu systému je vyveden do nativního Single-Page ovládacího panelu na bázi NiceGUI 2.x:

  • Interaktivní tabulky AG Grid (v32+) s vlastními Excel-style checkbox filtry (aggrid_filters.js).
  • Monitoring front, zpoždění API providerů a pingu PostgreSQL / Redis v reálném čase.
  • Průběžné filtrování podle dat s bezproblémovou integrací BI dashboardu Metabase přes podepsané JWT tokeny.