Shërbimi All File Converter është projektuar si një SaaS-sistem i shkallëzueshëm dhe i shpërndarë i bazuar në stack-un modern asinkron Python 3.12. Arkitektura është e ndarë në shtresa të pavarura: pranimi i ngjarjeve të rrjetit, orkestrimi i detyrave, ekzekutimi i izoluar i proceseve të rënda binare dhe qarku analitik.

1. Stack-u i përgjithshëm i teknologjive dhe arkitektura e sistemit

Në themel të platformës janë vendosur parimet e performancës së lartë (high-throughput), konsumit minimal të memories dhe mbrojtjes nga dështimet:

  • Telegram Bot Framework: Aiogram 3.13, që funksionon në modalitetin Webhook me vërtetim të tokenëve sekretë dhe filtra të personalizuar të ciklit jetësor të mesazheve.
  • Web gateway dhe REST API: FastAPI i bazuar në ASGI-serverin Uvicorn me dërgim asinkron të skedarëve binarë në formë stream (FileResponse) dhe pastrim në sfond përmes BackgroundTasks.
  • Brokeri i radhëve dhe cache: Redis 7 (menaxhimi i detyrave Celery, bllokimet kundër gjendjes së garës (race condition), mbrojtja nga brute force, ruajtja në cache e sesioneve).
  • Ekzekutuesi në sfond (Task Queue): Celery 5.4 me një grup punonjësish (workers) të dedikuar në një kontejner të izoluar converter_worker.
  • Baza e të dhënave: PostgreSQL 16 me shtresën ORM SQLAlchemy 2.0 (asyncpg), pishë lidhjesh të përhershme (20+10 overflow) dhe ripërsëritje automatike të transaksioneve që dështojnë (@db_retry).
  • Qarku i rrjetit: Tunelimi përmes Cloudflare Zero Trust me bllokim të qasjes së drejtpërdrejtë IP në server përmes Middleware.

2. Radhët asinkrone dhe izolimi i llogaritjeve të rënda (Celery + Redis)

Konvertimi i skedarëve multimedialë dhe paketave të zyrave krijon ngarkesa maksimale në CPU dhe RAM. Për të parandaluar bllokimin e procesit të përpunimit të mesazheve hyrëse në Telegram gjatë operacioneve të rënda, është zbatuar një izolim i rreptë:

  • Delegimi i detyrave në Redis: Gjatë zgjedhjes së formatit, trajtuesi i Telegram regjistron detyrën në bazën e të dhënave me statusin PROCESSING dhe vendos punën në radhën tasks.execute_conversion përmes Celery.
  • Kontejneri i izoluar i worker-it: Ekzekutimi i utiliteve të konvertimit ndodh në një Linux-kontejner të veçantë me kufirin e tij të kohës së procesorit dhe memories.
  • Kontrolli i ngrirjeve dhe timeout-et: Thirrjet e utiliteve të jashtme janë mbështjellë në një kontekst asinkron me kontroll të rreptë të kohës (conversion_timeout_sec = 180). Në rast se kapërcehet kufiri, procesi ndërpritet me dhunë përmes proc.kill(), duke liruar burimet.
  • Fallback i qëndrueshëm ndaj gabimeve: Në rast të padisponueshmërisë së përkohshme të brokerit Redis, detyra kapet automatikisht nga dispeçeri lokal asinkron dhe ekzekutohet direkt pa ndërprerje për përdoruesin.

3. Tubacioni i motorëve të specializuar të konvertimit

Për çdo lloj të dhënash përdoren utilite dhe biblioteka vendase të specializuara ngushtë:

  • Dokumentet dhe tabelat (LibreOffice): Paketë zyre pa ekran (headless) (soffice --headless) për renderim të saktë të DOCX, XLSX, PPTX, RTF, ODT në format PDF ose skedarë tekstualë.
  • Audio dhe video streaming (FFmpeg): Transkodim me shumë fije (multi-threaded) i kodekeve video (H.264), kodekeve audio (MP3, OGG Opus), nxjerrje e skenave zanore, gjenerim GIF (filtër Lanczos) dhe prerje katrore (1:1) e mesazheve video në Telegram.
  • Përpunim me shpejtësi të lartë i PDF (Poppler Utils): Utilitetet pdftotext (nxjerrje e menjëhershme e tekstit të formatuar në UTF-8) dhe pdftoppm (renderim faqe pas faqeje i PDF-ve në imazhe raster pa kosto shtesë nga LibreOffice).
  • Njohja optike e karaktereve (Tesseract OCR): Nxjerrje me rrjetë neurale e tekstit të shtypur nga skanime dhe fotografi në 40+ gjuhë.
  • Grafika raster dhe vektoriale: Bibliotekat Pillow (duke përfshirë mbështetjen për formatet HEIC dhe AVIF), CairoSVG për imazhe vektoriale dhe lottie për stikerët e animuar të Telegram (.TGS).
  • Libra, subtituj dhe shkronja (fonts): Motori Calibre (ebook-convert), parseri i subtitujve pysubs2 (SRT, VTT, ASS, SSA) dhe kompajluesi i shkronjave fonttools (kompresim Brotli në WOFF2).

4. Mbrojtja preventive e burimeve (System Guard)

Për të mbrojtur serverin nga rënia për shkak të mungesës së memories (OOM Killer), është instaluar shërbimi i diagnostikimit preventiv System Guard. Para se të pranojë një skedar për përpunim, sistemi kontrollon metrikat kryesore të hostit:

  • Memoria e lirë RAM: Minimumi 500 MB vëllim i lirë (guard_min_free_ram_mb).
  • Hapësira në disk: Minimumi 2 GB hapësirë e lirë në direktorinë /tmp (guard_min_free_disk_mb).
  • Radha e detyrave: Kufizimi i gjatësisë së radhës Celery (jo më shumë se 20 detyra në pritje).

Kur kapërcehen kufijtë, shërbimi aktivizon përkohësisht mbrojtjen (HTTP 503 / mesazh në chat), duke parandaluar mbingarkesën e serverit dhe duke dërguar një alarm të menjëhershëm te administratorët në Telegram.

5. Cikli jetësor i skedarëve dhe siguria (GDPR)

Arkitektura është projektuar sipas modelit Zero-Data-Footprint:

  • Skedarët e përdoruesve ngarkohen në një volum të mbrojtur tmp/conversions/ me parashtesa unike të bazuara në identifikuesit e detyrave.
  • Skedarët mbeten të aksesueshëm rreptësisht brenda sesionit të punës — jo më shumë se 15 minuta (900 sekonda).
  • Mbledhësi automatik i mbeturinave fshin skedarët origjinalë dhe të gatshëm menjëherë pas konfirmimit të dërgimit me sukses në chat ose pas skadimit të kohës së sesionit (timeout).
  • Baza e të dhënave PostgreSQL nuk ruan skedarë binarë ose tekste personale dokumentesh — në tabela regjistrohen vetëm metatëdhëna teknike të anonsuara (formatet, madhësia në bajt, koha e punës, statuset).

6. REST API universal për shërbimet e jashtme web

Shërbimi është projektuar që në fillim si një backend shumëplatformësh. Së bashku me bot-in, funksionon një ndërfaqe programimi e plotë dhe e mbrojtur për faqet web (për shembull, në Django) dhe bot-ë të palëve të treta:

  • GET /api/v1/formats — matricë dinamike JSON e drejtimeve të disponueshme të konvertimit, e sinkronizuar me cilësimet e Google Sheets.
  • POST /api/v1/convert — endpoint universal që pranon multipart/form-data (skedari, formato e synuar, ID e klientit të jashtëm) dhe kthen një rrjedhë (stream) të gatshme bajtësh në formë shkarkimi të drejtpërdrejtë.
  • Autorizim përmes Bearer token-ëve (WEBHOOK_REFRESH_TOKEN) me mbrojtje kundër sulmeve kohore përmes secrets.compare_digest.

7. Paneli i menaxhimit dhe Observability (NiceGUI + AG Grid)

Monitorimi i treguesve të biznesit dhe gjendjes së sistemit është nxjerrë në një panel menaxhimi vendas Single-Page të bazuar në NiceGUI 2.x:

  • Tabela ndëraktive AG Grid (v32+) me filtra të personalizuar checkbox të stilit Excel (aggrid_filters.js).
  • Monitorim në kohë reale i radhëve, vonesave të API-providerëve dhe ping-ut të PostgreSQL / Redis.
  • Filtrim ndërkohor sipas datave me integrim të pandërprerë të dashboard-it BI Metabase përmes JWT token-ëve të nënshkruar.