Usluga All File Converter dizajnirana je kao skalabilni distribuirani SaaS sustav temeljeni na modernom asinkronom Python 3.12 stogu. Arhitektura je podijeljena na neovisne slojeve: prijem mrežnih događaja, orkestraciju zadataka, izolirano izvršavanje teških binarnih procesa i analitički krug.

1. Opći tehnološki stog i sistemska arhitektura

Temelj platforme čine načela visokih performansi (high-throughput), minimalne potrošnje memorije i zaštite od kvarova:

  • Telegram Bot Framework: Aiogram 3.13, koji radi u Webhook načinu rada s validacijom tajnih tokena i prilagođenim filtrima životnog ciklusa poruka.
  • Web pristupnik i REST API: FastAPI na bazi ASGI poslužitelja Uvicorn s asinkronim streamanjem binarnih datoteka (FileResponse) i pozadinskim čišćenjem putem BackgroundTasks.
  • Broker reda čekanja i predmemorija: Redis 7 (upravljanje Celery zadacima, zaključavanja protiv stanja utrke, zaštita od brute-force napada, predmemoriranje sesija).
  • Pozadinski izvršitelj (Task Queue): Celery 5.4 s namjenskim skupom radnika (workers) u izoliranom spremniku converter_worker.
  • Baza podataka: PostgreSQL 16 s ORM slojem SQLAlchemy 2.0 (asyncpg), bazom trajnih konekcija (20+10 overflow) i automatskim ponovnim pokušajem neuspjelih transakcija (@db_retry).
  • Mrežni krug: Tuneliranje kroz Cloudflare Zero Trust s blokiranjem izravnog IP pristupa poslužitelju putem Middlewarea.

2. Asinkroni redovi čekanja i izolacija teških izračuna (Celery + Redis)

Konverzija medijskih datoteka i uredskih paketa stvara vršna opterećenja na CPU i RAM. Kako se proces obrade dolaznih poruka u Telegramu ne bi blokirao tijekom teških operacija, uvedena je stroga izolacija:

  • Delegiranje zadataka u Redis: Prilikom odabira formata, Telegram obrađivač registrira zadatak u bazi podataka sa statusom PROCESSING i stavlja zadatak u red čekanja tasks.execute_conversion putem Celeryja.
  • Izolirani spremnik radnika: Izvršavanje uslužnih programa za konverziju odvija se u zasebnom Linux spremniku s vlastitim ograničenjem procesorskog vremena i memorije.
  • Kontrola zastoja i vremenska ograničenja (timeouti): Pozivi vanjskih alata omotani su u asinkroni kontekst s finom kontrolom vremena (conversion_timeout_sec = 180). Premašivanjem ograničenja proces se prisilno prekida putem proc.kill(), oslobađajući resurse.
  • Rezervna opcija (Fallback): U slučaju privremene nedostupnosti Redis brokera, zadatak automatski preuzima lokalni asinkroni dispečer i izvršava ga izravno bez kvara za korisnika.

3. Cjevovod specijaliziranih mehanizama konverzije

Za svaku vrstu podataka koriste se usko specijalizirani izvorni uslužni programi i biblioteke:

  • Dokumenti i tablice (LibreOffice): Besglavi (headless) uredski paket (soffice --headless) za precizno renderiranje DOCX, XLSX, PPTX, RTF, ODT datoteka u PDF format ili tekstualne datoteke.
  • Streaming audio i video (FFmpeg): Višenitno prekodiranje video kodeka (H.264), audio kodeka (MP3, OGG Opus), ekstrakcija zvučnih zapisa, generiranje GIF-ova (Lanczos filtar) i četvrtasto obrezivanje (1:1) Telegram video poruka.
  • Obrada PDF-a visoke brzine (Poppler Utils): Uslužni programi pdftotext (trenutna ekstrakcija formatiranog teksta u UTF-8) i pdftoppm (stranica po stranica renderiranje PDF-a u rasterske slike bez LibreOffice overhead-a).
  • Optičko prepoznavanje znakova (Tesseract OCR): Ekstrakcija tiskanog teksta pomoću nevronske mreže sa skenova i fotografija na 40+ jezika.
  • Rasterska i vektorska grafika: Biblioteke Pillow (uključujući podršku za HEIC i AVIF formate), CairoSVG za vektorske slike i lottie za animirane Telegram naljepnice (.TGS).
  • Knjige, titlovi i fontovi: Mehanizam Calibre (ebook-convert), parser titlova pysubs2 (SRT, VTT, ASS, SSA) i kompajler fontova fonttools (Brotli kompresija u WOFF2).

4. Preventivna zaštita resursa (System Guard)

Kako bi se spriječilo rušenje poslužitelja zbog nedostatka memorije (OOM Killer), uveden je servis preventivne dijagnostike System Guard. Prije prihvaćanja datoteke na obradu, sustav provjerava ključne metrike hosta:

  • Slobodna radna memorija (RAM): Najmanje 500 MB slobodnog prostora (guard_min_free_ram_mb).
  • Prostor na disku: Najmanje 2 GB slobodnog prostora u direktoriju /tmp (guard_min_free_disk_mb).
  • Red čekanja zadataka: Ograničenje duljine reda čekanja Celeryja (ne više od 20 zadataka na čekanju).

Kada se ograničenja premaše, usluga privremeno uključuje zaštitu (HTTP 503 / poruka u chatu), sprječavajući preopterećenje poslužitelja i šaljući trenutno upozorenje administratorima u Telegramu.

5. Životni ciklus datoteka i sigurnost (GDPR)

Arhitektura je dizajnirana po modelu Zero-Data-Footprint:

  • Korisničke datoteke učitavaju se u zaštićeni volumen tmp/conversions/ s jedinstvenim prefiksima temeljenim na identifikatorima zadataka.
  • Datoteke ostaju dostupne isključivo unutar radne sesije — ne duže od 15 minuta (900 sekundi).
  • Automatski skupljač smeća briše izvorne i gotove datoteke odmah nakon potvrde uspješnog slanja u chat ili nakon isteka vremenskog ograničenja sesije.
  • PostgreSQL baza podataka ne pohranjuje binarne datoteke ili osobne tekstove dokumenata — u tablicama se bilježe samo anonimizirani tehnički metapodaci (formati, veličine u bajtovima, vrijeme rada, statusi).

6. Univerzalni REST API za vanjske web usluge

Usluga je od početka zamišljena kao multiplatformska pozadina (backend). Uz bot, funkcionira i potpuno zaštićeno programsko sučelje za web stranice (na primjer, na Django okviru) i botove trećih strana:

  • GET /api/v1/formats — dinamička JSON matrica dostupnih smjerova konverzije, sinkronizirana s postavkama Google tablica.
  • POST /api/v1/convert — univerzalna krajnja točka (endpoint) koja prihvaća multipart/form-data (datoteku, ciljni format, ID vanjskog klijenta) i vraća gotov tok bajtova u obliku izravnog preuzimanja.
  • Autorizacija pomoću Bearer tokena (WEBHOOK_REFRESH_TOKEN) sa zaštitom od napada vremenskim mjerenjem (timing attacks) kroz secrets.compare_digest.

7. Upravljačka ploča i Observability (NiceGUI + AG Grid)

Praćenje poslovnih pokazatelja i stanja sustava izvedeno je u izvornu Single-Page upravljačku ploču na bazi NiceGUI 2.x:

  • Interaktivne tablice AG Grid (v32+) s prilagođenim Excel-style filtara s kućicama za potvrdu (aggrid_filters.js).
  • Praćenje redova čekanja, kašnjenja API pružatelja i pinga PostgreSQL / Redis u stvarnom vremenu.
  • Sveobuhvatno filtriranje po datumima s besprijekornom integracijom Metabase BI nadzorne ploče putem potpisanih JWT tokena.