All File Converter zerbitzua Python 3.12 pila asynkrono modernoan oinarritutako SaaS sistema banatu eta eskalagarri gisa diseinatuta dago. Arkitektura geruza independenteetan banatuta dago: sareko gertaeren harrera, atazen orkestrazioa, prozesu bitar astunen exekuzio isolatua eta analisi-zirkuitua.

1. Teknologia-pila orokorra eta sistemaren arkitektura

Platfromaren oinarrian errendimendu handiko (high-throughput), memoria-kontsumo txikiko eta akatsen aurkako babesaren printzipioak daude:

  • Telegram Bot Framework: Aiogram 3.13, Webhook moduan lan egiten duena token sekretuen balioztapenarekin eta mezu-bizi-zikloko iragazki pertsonalizatuekin.
  • Web-pasabidea eta REST API: FastAPI Uvicorn ASGI zerbitzarian oinarrituta, fitxategi bitarren korronte-bidalketa asynkronoarekin (FileResponse) eta garbiketafonoa BackgroundTasks bidez.
  • Ilara-artekaria eta cachea: Redis 7 (Celery atazen kudeaketa, lasterketa-egoeren aurkako blokeoak, brute-force erasoen aurkako babesa, saioen katxeratzea).
  • Ataza-ilararen exekutatzailea (Task Queue): Celery 5.4, converter_worker edukiontzi isolatuan langile-multzo (pool) esklusibo batekin.
  • Datu-basea: PostgreSQL 16, SQLAlchemy 2.0 (asyncpg) ORM geruzarekin, konexio iraunkorren multzoarekin (20+10 overflow) eta huts egin duten transakzioen auto-berpentsaketarekin (@db_retry).
  • Sare-zirkuitua: Tunelkatzea Cloudflare Zero Trust bidez, zerbitzarirako zuzeneko IP-sarbidea Middleware bidez blokeatuta.

2. Ilara asynkronoak eta konputazio astunen isolamendua (Celery + Redis)

Media-fitxategien eta bulegoko paketeen bihurketak karga handiak sortzen ditu CPU eta RAM-ean. Telegram-eko sarrerako mezuen prozesamendua eragiketa astunetan ez blokeatzeko, isolamendu zorrotza ezarri da:

  • Atazak Redis-era delegatzea: Formatu bat hautatzean, Telegram-kudeatzaileak ataza bat erregistratzen du datu-basean PROCESSING estatusarekin eta tasks.execute_conversion ilaran jartzen du Celery bidez.
  • Langilearen (worker) edukiontzi isolatua: Bihurtze-utilitateen exekuzioa prozesadore-denbora eta memoria muga propioak dituen Linux edukiontzi bereizi batean gertatzen da.
  • Izozte-kontrolak eta denbora-mugak (timeouts): Kanpoko utilitateen deiak testuinguru asynkrono batean bilduta daude denbora-kontrol zorrotzarekin (conversion_timeout_sec = 180). Muga gainditzean, prozesua indarrez gelditzen da proc.kill() bidez, baliabideak askatuz.
  • Akatsen aurkako Fallback-a: Redis artekaria aldi baterako erabilgarri ez badago, ataza tokiko kudeatzaile asynkronoak bere gain hartzen du automatikoki eta zuzenean exekutatzen da erabiltzailearentzako arazorik gabe.

3. Bihurtze-motor espezializatuen katea (Pipeline)

Datu mota bakoitzerako utilitate eta liburutegi natibo espezializatuak erabiltzen dira:

  • Dokumentuak eta taulak (LibreOffice): Bulego-pakete burugabea (soffice --headless) DOCX, XLSX, PPTX, RTF, ODT PDF formatura edo testu-fitxategietara zehaztasunez errendatzeko.
  • Audio eta bideo streaminga (FFmpeg): Bideo-kodeken (H.264) eta audio-kodeken (MP3, OGG Opus) multy-hari bidezko birkodetzea, soinu-pisten erauzketa, GIF sorrera (Lanczos iragazkia) eta Telegram-eko bideo-mezuen koadraketa karratua (1:1).
  • Abiadura handiko PDF prozesamendua (Poppler Utils): pdftotext (formatudun testua berehala ateratzea UTF-8n) eta pdftoppm (PDF orrialdeen errendatzea irudi rasterizatuetan LibreOffice-ren gainkosturik gabe) utilitateak.
  • Reconezamendu optikoa (Tesseract OCR): Eskanertako eta argazkietako testu inprimatua sare neuronalen bidez ateratzea 40 hizkuntza baino gehiagotan.
  • Raster eta bektorio grafikoak: Pillow liburutegiak (HEIC eta AVIF formatuen euskarria barne), CairoSVG irudi vektorialetarako eta lottie Telegram-eko eranskine animatuetarako (.TGS).
  • Liburuak, azpitituluak eta letra-tipoak: Calibre motorra (ebook-convert), pysubs2 azpititulu parserra (SRT, VTT, ASS, SSA) eta fonttools letra-tipo konpilatzailea (Brotli konpresioa WOFF2-n).

4. Baliabideak prebentzio bidez babestea (System Guard)

Memoria faltagatik zerbitzaria erortzea ekiditeko (OOM Killer), System Guard diagnostiko prebentiboko zerbitzua ezarri da. Fitxategia prozesatzen hasi aurretik, sistemak ostalariaren funtsezko metrikak egiaztatzen ditu:

  • Memoria erabilgarria (RAM): Gutxienez 500 MB libre (guard_min_free_ram_mb).
  • Disko-espazioa: Gutxienez 2 GB libre /tmp direktorioan (guard_min_free_disk_mb).
  • Ataza-ilara: Celery ilararen luzeraren muga (gehienez 20 ataza zain).

Mugak gainditzen direnean, zerbitzuak babesa aktibatzen du aldi baterako (HTTP 503 / mezua txatean), zerbitzariaren gainkarga ekidingo du eta berehalako oharra bidaliko die administratzaileei Telegram-en.

5. Fitxategien bizi-zikloa eta segurtasuna (GDPR)

Arkitektura Zero-Data-Footprint modeloaren arabera diseinatuta dago:

  • Erabiltzaileen fitxategiak tmp/conversions/ bolumen seguruan kargatzen dira, atazen identifikatzaileetan oinarritutako aurrizki unikoekin.
  • Fitxategiak lan-saioaren barruan bakarrik geratzen dira eskuragarri — gehienez 15 minutu (900 segundu).
  • Zabor-biltzaile automatikoak jatorrizko fitxategiak eta prest daudenak ezabatzen ditu txatean arrakastaz bidali dela konfirmatu bezain laster edo saioaren denbora-muga amaitzean.
  • PostgreSQL datu-baseak ez du fitxategi biktarrik edo dokumentuen testu pertsonalik gordetzen — tauletan metadata tekniko anonimizatuak bakarrik erregistratzen dira (formatuak, tamaina bytetan, lan-denbora, estatusak).

6. Kanpoko web-zerbitzuetarako REST API unibertsala

Zerbitzua hasieratik plataforma anitzeko backend gisa diseinatuta dago. Bot-az gain, webguneetarako (adibidez, Django-n oinarrituta) eta hirugarrenen bot-etarako software-interfaze seguru oso bat funtzionatzen du:

  • GET /api/v1/formats — bihurtze-norabide eskuragarrien JSON-matrize dinamikoa, Google Sheets-eko ezarpenekin sinkronizatuta.
  • POST /api/v1/convert — multipart/form-data onartzen duen endpoint unibertsala (fitxategia, helburu-formatua, kanpoko bezeroaren IDa) eta byte-korrontea deskarga zuzen gisa itzultzen duena.
  • Bearer token bidezko baimena (WEBHOOK_REFRESH_TOKEN) denbora-erasoen aurkako babesarekin secrets.compare_digest erabiliz.

7. Kontrol-panela eta Observability (NiceGUI + AG Grid)

Negozio-adierazleen eta sistemaren egoeraren monitorizazioa NiceGUI 2.x-n oinarritutako jatorrizko Single-Page kontrol-panel batera eraman da:

  • AG Grid (v32+) taula interaktiboak Excel estiloko koadro-egiaztapeneko iragazki pertsonalizatuekin (aggrid_filters.js).
  • Ilaren, API hornitzaileen atzerapenen eta PostgreSQL / Redis-en ping-aren denbora errealeko monitorizazioa.
  • Daten araberako iragazketa gardena, sinatutako JWT token bidez Metabase BI-dashboard-aren integrazio ezin hobearekin.