Is-servizz All File Converter huwa ddisinjat bħala sistema SaaS distribwita u skalabbli fuq bażi tal-istack asinkroniku modern Python 3.12. L-arkitettura hija maqsuma f'saffi indipendenti: ir-riċeviment ta' avvenimenti tan-netwerk, l-orkestrazzjoni tal-kompiti, l-eżekuzzjoni iżolata ta' proċessi binarji tqal u ċ-ċirkwit analitiku.

1. Stack teknoloġiku ġenerali u arkitettura tas-sistema

Il-pedament tal-pjattaforma jinkludi l-prinċipji ta' prestazzjoni għolja (high-throughput), konsum minimu ta' memorja u protezzjoni kontra ħsarat:

  • Telegram Bot Framework: Aiogram 3.13, li jaħdem fil-modalità Webhook b'validazzjoni ta' tokens siguri u filtri tad-dwana taċ-ċiklu tal-ħajja tal-messaġġi.
  • Web gateway u REST API: FastAPI ibbażat fuq l-ASGI server Uvicorn b'kunsinna asinkronika ta' streaming ta' fajls binarji (FileResponse) u tindif fl-isfond permezz ta' BackgroundTasks.
  • Broker tal-kjuwijiet u cache: Redis 7 (ġestjoni tal-kompiti ta' Celery, imblokki kontra l-istat ta' tiġrija, protezzjoni kontra brute-force, caching tas-sessjonijiet).
  • Eżekutur fl-isfond (Task Queue): Celery 5.4 b'pool dedikat ta' workers f'kontenitur iżolat converter_worker.
  • Bażi tad-data: PostgreSQL 16 bis-saff ORM SQLAlchemy 2.0 (asyncpg), pool ta' konnessjonijiet persistenti (20+10 overflow) u awtorinovazzjoni ta' transazzjonijiet falluti (@db_retry).
  • Ċirkwit tan-netwerk: Tunnellar permezz ta' Cloudflare Zero Trust b'imblokk tal-aċċess dirett tal-IP lis-server permezz tal-Middleware.

2. Kjuwijiet asinkroniċi u iżolament ta' komputazzjonijiet tqal (Celery + Redis)

Il-konverżjoni ta' fajls tal-midja u pakketti tal-uffiċċju toħloq tagħbijiet massimi fuq is-CPU u r-RAM. Sabiex il-proċess tal-ipproċessar tal-messaġġi li jidħolu f'Telegram ma jiġix ibblokkat waqt operazzjonijiet tqal, ġie implimentat iżolament strett:

  • Delegazzjoni tal-kompiti lil Redis: Meta jintgħażel format, l-handler tat-Telegram jirreġistra l-kompitu fil-bażi tad-data bl-istatus PROCESSING u jqiegħed il-kompitu fil-kju tasks.execute_conversion permezz ta' Celery.
  • Kontenitur iżolat tal-worker: L-eżekuzzjoni tal-utilitajiet ta' konverżjoni sseħħ f'kontenitur Linux separat bil-limitu tiegħu stess ta' ħin tal-proċessur u memorja.
  • Kontroll ta' ffriżar u timeouts: Is-sejħiet għal utilitajiet esterni huma mgeżwra f'kuntest asinkroniku b'kontroll strett tal-ħin (conversion_timeout_sec = 180). Meta jinqabeż il-limitu, il-proċess jiġi terminat bil-forza permezz ta' proc.kill(), filwaqt li jiġו eżawriti r-riżorsi.
  • Fallback reżistenti għall-fallimenti: F'każ ta' nuqqas temporanju ta' disponibbiltà tal-broker Redis, il-kompitu jiġi interċettat awtomatikament mid-dispatċer asinkroniku lokali u jiġi eżegwit direttament mingħajr falliment għall-utent.

3. Pipeline ta' magni speċjalizzati ta' konverżjoni

Għal kull tip ta' data, jintużaw utilitajiet u libreriji natingi speċjalizzati ħafna:

  • Dokumenti u tabelli (LibreOffice): Pakkett tal-uffiċċju mingħajr ras (soffice --headless) għal render preċiż ta' DOCX, XLSX, PPTX, RTF, ODT f'format PDF jew fajls tat-test.
  • Awdjo u vidjow ta' streaming (FFmpeg): Transkodifikazzjoni b'ħafna flussi ta' codeks tal-vidjow (H.264), codeks tal-awdjo (MP3, OGG Opus), estrazzjoni ta' tracks tal-awdjo, ġenerazzjoni ta' GIF (filtru Lanczos) u ħdim kwadru (1:1) ta' messaġġi tal-vidjow f'Telegram.
  • Ipproċessar ta' veloċità għolja ta' PDF (Poppler Utils): L-utilitajiet pdftotext (estrazzjoni istantanja ta' test ifformattjat f'UTF-8) u pdftoppm (render minn paġna għal paġna ta' PDF f'immaġini raster mingħajr spejjeż addizzjonali ta' LibreOffice).
  • Rikonoxximent ottiku (Tesseract OCR): Estrazzjoni bbażata fuq in-newrons ta' test stampat minn skans u ritratti f'aktar minn 40 lingwa.
  • Grafika raster u vettorjali: Il-libreriji Pillow (inkluż appoġġ għall-format HEIC u AVIF), CairoSVG għal immaġini vettorjali u lottie għal stikers animati ta' Telegram (.TGS).
  • Ktieb, sottotitoli u fonts: Il-magna Calibre (ebook-convert), parser tas-sottotitoli pysubs2 (SRT, VTT, ASS, SSA) u l-kompilatur tal-fonts fonttools (kompressjoni Brotli f'WOFF2).

4. Protezzjoni preventiva tar-riżorsi (System Guard)

Biex jiġi protett is-server milli jiġġarraf minħabba nuqqas ta' memorja (OOM Killer), ġie introdott is-servizz ta' dijanjostika preventiva System Guard. Qabel ma jaċċetta fajl għall-ipproċessar, is-sistema tiċċekkja l-metriċi ewlenin tal-host:

  • Memorja RAM libera: Minimament 500 MB ta' spazju ħieles (guard_min_free_ram_mb).
  • Spazju fuq id-diska: Minimament 2 GB ta' spazju ħieles fid-direttorju /tmp (guard_min_free_disk_mb).
  • Kju tal-kompiti: Limitazzjoni tat-tul tal-kju ta' Celery (mhux aktar minn 20 kompitu li qed jistennew).

Meta jinqabżu l-limiti, is-servizz temporanjament jixgħel il-protezzjoni (HTTP 503 / messaġġ fiċ-chat), u b'hekk jipprevjeni t-tagħbija żejda tas-server u jibgħat alert istantanju lill-amministraturi f'Telegram.

5. Ċiklu tal-ħajja tal-fajls u sigurtà (GDPR)

L-arkitettura hija ddisinjata skont il-mudell Zero-Data-Footprint:

  • Il-fajls tal-utenti jitniżżlu f'volum sigur tmp/conversions/ b'prefissi uniċi bbażati fuq l-identifikaturi tal-kompiti.
  • Il-fajls jibqgħu disponibbli strettament fil-limiti tas-sessjoni tax-xogħol — mhux aktar minn 15-il minuta (900 sekonda).
  • Il-ġbir awtomatiku ta' żibel (garbage collector) iħassar il-fajls oriġinali u l-fajls lesti immedjatament wara l-konferma tat-tqassim b'suċċess fiċ-chat jew meta jiskadi t-timeout tas-sessjoni.
  • Il-bażi tad-data PostgreSQL ma taħżinx fajls binarji jew testi personali ta' dokumenti — fit-tabelli jiġu ffissati biss metadata teknika anonyma (formati, daqsijiet f'bytes, ħin ta' xogħol, status).

6. REST API universali għal servizzi tal-web esterni

Is-servizz huwa ddisinjat oriġinarjament bħala backend multi-pjattaforma. Flimkien mal-bot, jaħdem interface tal-programm sigur u sħiħ għal websajts (pereżempju, fuq Django) u bots ta' partijiet terzi:

  • GET /api/v1/formats — matriċi dinamika JSON ta' direzzjonijiet disponibbli għall-konverżjoni, sinkronizzata mas-settings tal-Google Sheets.
  • POST /api/v1/convert — endpoint universali li jaċċetta multipart/form-data (fajl, format fil-mira, ID tal-klijent estern) u jagħti fluss lest ta' bytes fil-forma ta' tniżżil dirett.
  • Awtorizzazzjoni permezz ta' Bearer tokens (WEBHOOK_REFRESH_TOKEN) b'protezzjoni kontra attaki ta' żmien permezz ta' secrets.compare_digest.

7. Pannell tal-kontroll u Observability (NiceGUI + AG Grid)

Il-monitoraġġ tal-indikaturi tan-negozju u l-istat tas-sistema ġie trasferit għal pannell tal-kontroll nativ Single-Page ibbażat fuq NiceGUI 2.x:

  • Tabelli interattivi AG Grid (v32+) b'filtri custom ta' checkbox fi stil Excel (aggrid_filters.js).
  • Monitoraġġ f'ħin reali tal-kjuwijiet, dewmien tal-fornituri tal-API u ping ta' PostgreSQL / Redis.
  • Filtrazzjoni trasversali skont id-dati b'integrazzjoni bla xkiel tad-dashboards tal-BI Metabase permezz ta' JWT tokens iffirmati.