Az All File Converter szolgáltatást skálázható, elosztott SaaS-rendszerként tervezték, amely a modern aszinkron Python 3.12 stacken alapul. Az architektúra független rétegekre oszlik: hálózati események fogadása, feladatok orchestrációja, a nehéz bináris folyamatok izolált végrehajtása és az analitikai áramkör.

1. Általános technológiai stack és rendszeraρχitektúra

A platform alapját a nagy teljesítmény (high-throughput), a minimális memóriafogyasztás és a hibák elleni védelem elvei képezik:

  • Telegram Bot Framework: Aiogram 3.13, amely Webhook módban működik titkos tokenek érvényesítésével és egyedi üzenet-életciklus szűrőkkel.
  • Webes átjáró és REST API: FastAPI Uvicorn ASGI-szerveren alapuló aszinkron bináris fájlfolyam-továbbítással (FileResponse) és háttértakarítással a BackgroundTasks segítségével.
  • Sorban állás bróker és cache: Redis 7 (Celery feladatok kezelése, race condition zárolások, brute-force elleni védelem, munkamenet-caching).
  • Háttér-végrehajtó (Task Queue): Celery 5.4 dedikált munkáskészlettel egy izolált converter_worker konténerben.
  • Adatbázis: PostgreSQL 16 SQLAlchemy 2.0 (asyncpg) ORM-réteggel, állandó kapcsolatok pooljával (20+10 overflow) és a hibás tranzakciók automatikus újraküldésével (@db_retry).
  • Hálózati áramkör: Alagútépítés Cloudflare Zero Trust használatával, közvetlen IP-hozzáférés blokkolásával a szerverhez Middleware-en keresztül.

2. Aszinkron sorok és a nehéz számítások izolációja (Celery + Redis)

A médiafájlok és az irodami csomagok konvertálása csúcsterhelést jelent a CPU-nak és a RAM-nak. Annak érdekében, hogy a Telegram bejövő üzeneteinek feldolgozása ne blokkolódjon a nehéz műveletek alatt, szigorú izolációt valósítottak meg:

  • Feladatok delegálása a Redisbe: Formátumválasztáskor a Telegram-kezelő regisztrálja a feladatot az adatbázisban PROCESSING státusszal, és a tasks.execute_conversion sorba állítja a Celery-n keresztül.
  • Izolált worker konténer: A konverziós segédprogramok futtatása egy külön Linux-konténerben történik, saját processzoridő- és memóriakorláttal.
  • Fagyásvezérlés és időtúllépések: A külső segédprogramok hívásai egy aszinkron kontextusba vannak ágyazva szigorú idővezérléssel (conversion_timeout_sec = 180). A limit túllépése esetén a folyamat kényszerítve leáll a proc.kill() által, felszabadítva az erőforrásokat.
  • Hibatűrő Fallback: A Redis bróker átmeneti elérhetetlensége esetén a feladatot a helyi aszinkron diszpécser automatikusan átveszi, és a felhasználó számára hiba nélkül, közvetlenül hajtja végre.

3. Speciális konverziós motorok pipeline-ja

Minden adattípushoz szigorúan szakosodott natív segédprogramokat és könyvtárakat használnak:

  • Dokumentumok és táblázatok (LibreOffice): Headless irodai csomag (soffice --headless) a DOCX, XLSX, PPTX, RTF, ODT PDF formátumba vagy szöveges fájlokba történő pontos rendereléséhez.
  • Streaming audio és video (FFmpeg): Videokodekek többszálas átkódolása (H.264), audiokodekek (MP3, OGG Opus), hangcsíkok kinyerése, GIF generálás (Lanczos-szűrő) és a Telegram videóüzenetek négyzethálós kivágása (1:1).
  • Nagy sebességű PDF-feldolgozás (Poppler Utils): pdftotext (formázott szöveg azonnali kinyerése UTF-8-ba) és pdftoppm (PDF oldalszintű renderelése raszteres képekké LibreOffice rezsi nélkül) segédprogramok.
  • Optikai karakterfelismerés (Tesseract OCR): Nyomtatott szöveg neurális hálózati kinyerése szkennelésekről és fényképekről 40+ nyelven.
  • Raszteres és vektoros grafika: Pillow könyvtárak (beleértve a HEIC és AVIF formátumok támogatását), CairoSVG vektoros képekhez és lottie az animált Telegram matricákhoz (.TGS).
  • Könyvek, feliratok és betűtípusok: Calibre motor (ebook-convert), pysubs2 felirat-parser (SRT, VTT, ASS, SSA) és fonttools betűtípus-fordító (Brotli tömörítés WOFF2-ben).

4. Megelőző erőforrás-védelem (System Guard)

A szerver memória-hiány miatti leállásának (OOM Killer) megakadályozása érdekében bevezették a System Guard megelőző diagnosztikai szolgáltatást. Mielőtt a fájlt feldolgozásra elfogadnák, a rendszer ellenőrzi a gazdagép kulcsfontosságú metrikáit:

  • Szabad memória (RAM): Legalább 500 MB szabad terület (guard_min_free_ram_mb).
  • Lemezterület: Legalább 2 GB szabad hely a /tmp könyvtárban (guard_min_free_disk_mb).
  • Feladatsor: Celery sorhossz korlátozás (legfeljebb 20 várakozó feladat).

A határértékek túllépése esetén a szolgáltatás átmenetileg bekapcsolja a védelmet (HTTP 503 / üzenet a csevegésben), megakadályozva a szerver túlterhelését, és azonnali riasztást küld az adminisztrátoroknak Telegramon.

5. Fájlok életciklusa és biztonság (GDPR)

Az architektúrát a Zero-Data-Footprint modell szerint tervezték:

  • A felhasználói fájlok a tmp/conversions/ védett kötetre töltődnek fel egyedi előtagokkal a feladatazononosítók alapján.
  • A fájlok szigorúan a munkamenet keretein belül maradnak elérhetők — legfeljebb 15 percig (900 másodperc).
  • Az automatikus szemétgyűjtő törli az eredeti és kész fájlokat közvetlenül a csevegésbe történő sikeres elküldés visszaigazolása után, vagy a munkamenet időtúllépésének lejártaikor.
  • A PostgreSQL adatbázis nem tárol bináris fájlokat vagy személyes dokumentumszövegeket — a táblák csak anonimizált műszaki metaadatokat rögzítenek (formátumok, méretek bájtokban, futási idő, státuszok).

6. Univerzális REST API külső webszolgáltatások számára

A szolgáltatást kezdetben multiplatform backendként tervezték. A bot mellett teljes értékű, védett szoftveres interfész működik webhelyek (például Django alapúak) és külső botok számára:

  • GET /api/v1/formats — az elérhető konverziós irányok dinamikus JSON-mátrixa, szinkronizálva a Google Táblázatok beállításaival.
  • POST /api/v1/convert — univerzális végpont, amely elfogadja a multipart/form-data-t (fájl, célformátum, külső ügyfél ID) és kész bájtok áramát adja vissza közvetlen letöltésként.
  • Hitelesítés Bearer tokenekkel (WEBHOOK_REFRESH_TOKEN) időalapú támadások elleni védelemmel a secrets.compare_digest használatával.

7. Vezérlőpult és Observability (NiceGUI + AG Grid)

Az üzleti mutatók és a rendszerállapot felügyelete egy natív Single-Page vezérlőpultba lett kivezetve a NiceGUI 2.x alapján:

  • Interaktív AG Grid (v32+) táblázatok egyedi Excel-stílusú jelölőnégyzet-szűrőkkel (aggrid_filters.js).
  • Sorok, az API-szolgáltatók késleltetésének, valamint a PostgreSQL / Redis ping valós idejű figyelése.
  • Átfogó dátum szerinti szűrés a Metabase BI-irányítópult zökkenőmentes integrációjával aláírt JWT-tokeneken keresztül.