Storitev All File Converter je zasnovana kot razširljiv porazdeljen SaaS sistem na podlagi sodobnega asinhronega sklada Python 3.12. Arhitektura je razdeljena na neodvisne plasti: sprejem omrežnih dogodkov, orkestracija opravil, izolirano izvajanje težkih binarnih procesov in analitična zanka.

1. Splošni sklad tehnologij in sistemska arhitektura

Osnova platforme temelji na načelih visoke prepustnosti (high-throughput), minimalne porabe pomnilnika in zaščite pred napakami:

  • Telegram Bot Framework: Aiogram 3.13, ki deluje v načinu Webhook z validacijo varnostnih žetonov in prilagojenimi filtri življenjskega cikla sporočil.
  • Spletni prehod in REST API: FastAPI na podlagi ASGI strežnika Uvicorn z asinhronim pretočnim pošiljanjem binarnih datotek (FileResponse) in ozadnjim čiščenjem prek BackgroundTasks.
  • Posrednik čakalnih vrst in predpomnilnik: Redis 7 (upravljanje opravil Celery, zaklepanje stanja tekme, zaščita pred poskusi vdora z ugibanjem, predpomnjenje sej).
  • Izvajalec v ozadju (Task Queue): Celery 5.4 z namenskim bazenom delavcev v izoliranem vsebniku converter_worker.
  • Baza podatkov: PostgreSQL 16 z ORM plastjo SQLAlchemy 2.0 (asyncpg), bazenom stalnih povezav (20+10 overflow) in samodejnim ponovnim poskusom neuspešnih transakcij (@db_retry).
  • Omrežni obod: Tuneliranje prek Cloudflare Zero Trust z blokiranjem neposrednega IP dostopa do strežnika preko Middleware.

2. Asinhrone čakalne vrste in izolacija težkih izračunov (Celery + Redis)

Pretvorba predstavnostnih datotek in pisarniških paketov ustvarja vršne obremenitve na CPE in pomnilnik. Da se obdelava dohodnih sporočil v Telegramu ne bi blokirala med težkimi operacijami, je vzpostavljena stroga izolacija:

  • Delegiranje opravil v Redis: Pri izbiri formata izvajalec Telegram registrira opravilo v bazi podatkov s statusom PROCESSING in doda nalogo v čakalno vrsto tasks.execute_conversion preko Celery.
  • Izoliran vsebnik delavca: Izvajanje orodij za pretvorbo poteka v ločenem Linux vsebniku z lastno omejitvijo časa procesorja in pomnilnika.
  • Nadzor zamrznitev in časovne omejitve: Klici zunanjih orodij so zaviti v asinhroni kontekst s strogim časovnim nadzorom (conversion_timeout_sec = 180). Ob prekoračitvi omejitve se proces prisilno prekine prek proc.kill(), kar sprosti vire.
  • Zanesljiv nadomestni mehanizem (Fallback): Ob začasni nedosegljivosti posrednika Redis nalogo samodejno prestreže lokalni asinhroni razporejevalnik in jo izvede neposredno brez napake za uporabnika.

3. Cevovod specializiranih pogonov za pretvorbo

Za vsak tip podatkov se uporabljajo ozko specializirana domača orodja in knjižnice:

  • Dokumenti in preglednice (LibreOffice): Brezglavi pisarniški paket (soffice --headless) za natančno upodabljanje DOCX, XLSX, PPTX, RTF, ODT v format PDF ali besedilne datoteke.
  • Pretočni zvok in video (FFmpeg): Večnitno prekodiranje video kodekov (H.264), avdio kodekov (MP3, OGG Opus), pridobivanje zvočnih sledi, generiranje GIF (Lanczos filter) in kvadratno obrezovanje (1:1) video sporočil Telegram.
  • Visokohitrostna obdelava PDF (Poppler Utils): Orodja pdftotext (takojšnje pridobivanje formatiranega besedila v UTF-8) in pdftoppm (upodabljanje PDF strani v rastrske slike brez režijskih stroškov LibreOffice).
  • Optično prepoznavanje znakov (Tesseract OCR): Nevronsko mrežno pridobivanje natisnjenega besedila s skenov in fotografij v več kot 40 jezikih.
  • Rastrska in vektorska grafika: Knjižnice Pillow (vključno s podporo za formata HEIC in AVIF), CairoSVG za vektorske slike in lottie za animirane nalepke Telegram (.TGS).
  • Knjige, podnapisi in pisave: Pogon Calibre (ebook-convert), razčlenjevalnik podnapisov pysubs2 (SRT, VTT, ASS, SSA) in prevajalnik pisav fonttools (Brotli stiskanje v WOFF2).

4. Preventivna zaščita virov (System Guard)

Za zaščito pred sesutjem strežnika zaradi pomanjkanja pomnilnika (OOM Killer) je vgrajena storitev preventivne diagnostike System Guard. Pred sprejemom datoteke v obdelavo sistem preveri ključne metrike gostitelja:

  • Prosti delovni pomnilnik (RAM): Najmanj 500 MB proste prostornine (guard_min_free_ram_mb).
  • Prostor na disku: Najmanj 2 GB prostega prostora v imeniku /tmp (guard_min_free_disk_mb).
  • Čakalna vrsta opravil: Omejitev dolžine čakalne vrste Celery (največ 20 čakajočih opravil).

Ob prekoračitvi omejitev storitev začasno vklopi zaščito (HTTP 503 / sporočilo v klepetu), s čimer prepreči preobremenitev strežnika in pošlje takojšnje opozorilo skrbnikom v Telegramu.

5. Življenjski cikel datotek in varnost (GDPR)

Arhitektura je zasnovana po modelu Zero-Data-Footprint:

  • Uporabniške datoteke se naložijo v varen nosilec tmp/conversions/ z edinstvenimi predponami na podlagi identifikatorjev opravil.
  • Datoteke ostanejo dostopne strogo v okviru delovne seje – največ 15 minut (900 sekund).
  • Samodejni zbiralnik smeti izbriše izvirne in pripravljene datoteke takoj po potrditvi uspešnega pošiljanja v klepet ali po preteku časovne omejitve seje.
  • Baza podatkov PostgreSQL ne shranjuje binarnih datotek ali osebnih besedil dokumentov – v tabelah se beležijo samo anonimizirani tehnični metapodatki (formati, velikosti v bajtih, čas delovanja, statusi).

6. Univerzalni REST API za zunanje spletne storitve

Storitev je že od začetka zasnovana kot večplatformsko zaledje. Poleg bota deluje popoln zaščiten programski vmesnik za spletna mesta (na primer v Django) in zunanje bote:

  • GET /api/v1/formats — dinamična JSON matrika razpoložljivih smeri pretvorbe, sinhronizirana z nastavitvami Google Preglednic.
  • POST /api/v1/convert — univerzalna končna točka, ki sprejema multipart/form-data (datoteko, ciljni format, ID zunanjega odjemalca) in vrača pripravljen tok bajtov v obliki neposrednega prenosa.
  • Avtorizacija prek Bearer žetonov (WEBHOOK_REFRESH_TOKEN) z zaščito pred časovnimi napadi prek secrets.compare_digest.

7. Upravljalna plošča in Observability (NiceGUI + AG Grid)

Spremljanje poslovnih kazalnikov in stanja sistema je preneseno v domačo nadzorno ploščo enozaslonske aplikacije (Single-Page) na podlagi NiceGUI 2.x:

  • Interaktivne tabele AG Grid (v32+) s prilagojenimi filtri potrditvenih polj v Excel slogu (aggrid_filters.js).
  • Spremljanje čakalnih vrst, zakasnitev ponudnikov API in pinga PostgreSQL / Redis v realnem času.
  • Celovito filtriranje po datumih z brezhibno integracijo BI nadzorne plošče Metabase prek podpisanih JWT žetonov.