Ang serbisyong All File Converter ay idinisenyo bilang isang nasusukat na ipinamahaging sistema ng SaaS batay sa modernong asynchronous na Python 3.12 stack. Ang arkitektura ay nahahati sa mga independiyenteng layer: pagtanggap ng mga kaganapan sa network, pag-orchestrate ng gawain, nakahiwalay na pagpapatupad ng mabibigat na proseso ng binary at analytical circuit.

1. Pangkalahatang Stack ng Teknolohiya at Arkitektura ng Sistema

Ang plataporma ay batay sa mga prinsipyo ng mataas na pagganap (high-throughput), minimum na pagkonsumo ng memorya at proteksyon laban sa mga pagkabigo:

  • Telegram Bot Framework: Aiogram 3.13, na tumatakbo sa Webhook mode na may pag-validate ng mga lihim na token at pasadyang mga filter ng ikot ng buhay ng mensahe.
  • Web Gateway at REST API: FastAPI batay sa Uvicorn ASGI server na may asynchronous streaming output ng mga binary file (FileResponse) at background cleaning sa pamamagitan ng BackgroundTasks.
  • Queue Broker at Cache: Redis 7 (pamamahala ng mga gawain ng Celery, race condition locks, proteksyon laban sa brute force, pag-cache ng session).
  • Background Executor (Task Queue): Celery 5.4 na may nakalaang pool ng mga manggagawa sa isang nakahiwalay na lalagyan ng converter_worker.
  • Database: PostgreSQL 16 na may ORM layer SQLAlchemy 2.0 (asyncpg), persistent connection pool (20+10 overflow) at awtomatikong muling pagtatangka ng mga nabigong transaksyon (@db_retry).
  • Network Circuit: Tunnels sa pamamagitan ng Cloudflare Zero Trust na may direktang pag-block ng IP access sa server sa pamamagitan ng Middleware.

2. Asynchronous Queues at Isolation ng Mabibigat na Pagkalkula (Celery + Redis)

Ang pag-convert ng mga media file at office package ay lumilikha ng mga peak load sa CPU at RAM. Upang matiyak na ang proseso ng pagproseso ng mga papasok na mensahe sa Telegram ay hindi naka-block sa panahon ng mabibigat na operasyon, ipinatupad ang mahigpit na paghihiwalay:

  • Paghinto ng mga Gawain sa Redis: Kapag pumipili ng isang format, ang handler ng Telegram ay nagrehistro ng isang gawain sa DB na may katayuan na PROCESSING at inilalagay ang gawain sa tasks.execute_conversion queue sa pamamagitan ng Celery.
  • Nakahiwalay na Lalagyan ng Manggagawa: Ang pagpapatupad ng mga utility ng conversion ay nagaganap sa isang hiwalay na lalagyan ng Linux na may sarili nitong limitasyon sa oras ng processor at memorya.
  • Pagkontrol sa Pag-freeze at Mga Timeout: Ang mga tawag sa mga panlabas na kagamitan ay nakabalot sa isang asynchronous na konteksto na may mahigpit na kontrol sa oras (conversion_timeout_sec = 180). Kapag lumampas ang limitasyon, ang proseso ay sapilitang tinatapos sa pamamagitan ng proc.kill(), na nagpapalaya sa mga mapagkukunan.
  • Fault-Tolerant Fallback: Sa pansamantalang kawalan ng kakayahan ng Redis broker, ang gawain ay awtomatikong nahaharang ng lokal na asynchronous dispatcher at direktang isinasagawa nang walang pagkabigo para sa gumagamit.

3. Pipeline ng mga Espesyal na Engine ng Conversion

Para sa bawat uri ng data, ginagamit ang mga nag-iisang espesyal na katutubong utility at library:

  • Mga Dokumento at Talahanayan (LibreOffice): Headless office package (soffice --headless) para sa tumpak na pag-render ng DOCX, XLSX, PPTX, RTF, ODT sa format na PDF o mga text file.
  • Streaming Audio at Video (FFmpeg): Multithreaded transcoding ng mga video codec (H.264), audio codec (MP3, OGG Opus), pagkuha ng mga audio track, pagbuo ng GIF (Lanczos filter) at square cropping (1:1) ng mga mensahe ng video sa Telegram.
  • Mabilis na Pagproseso ng PDF (Poppler Utils): Ang mga utility na pdftotext (mabilis na pagkuha ng naka-format na teksto sa UTF-8) at pdftoppm (pahina-sa-pahinang pag-render ng PDF sa mga raster na imahe nang walang mga overhead ng LibreOffice).
  • Optical Character Recognition (Tesseract OCR): Neural network extraction ng naka-print na teksto mula sa mga scan at larawan sa mahigit 40 wika.
  • Raster at Vector Graphics: Mga library na Pillow (kabilang ang suporta para sa mga format na HEIC at AVIF), CairoSVG para sa mga vector image at lottie para sa mga animated na sticker ng Telegram (.TGS).
  • Mga Aklat, Subtitle at Font: Ang engine na Calibre (ebook-convert), subtitle parser na pysubs2 (SRT, VTT, ASS, SSA) at font compiler na fonttools (Brotli compression sa WOFF2).

4. Preventative Resource Protection (System Guard)

Upang maprotektahan laban sa pag-crash ng server dahil sa kakulangan ng memorya (OOM Killer), ipinakilala ang serbisyo ng preventive diagnostics na System Guard. Bago tanggapin ang file para sa pagproseso, sinusuri ng sistema ang mga pangmetrikang sukatan ng host:

  • Libreng RAM: Minimum na 500 MB ng libreng volume (guard_min_free_ram_mb).
  • Espasyo sa Disk: Minimum na 2 GB ng libreng espasyo sa direktoryo ng /tmp (guard_min_free_disk_mb).
  • Task Queue: Limitasyon sa haba ng Celery queue (hindi hihigit sa 20 naghihintay na gawain).

Kapag nalampasan ang mga limitasyon, pansamantalang pinapagana ng serbisyo ang proteksyon (HTTP 503 / mensahe sa chat), pinipigilan ang labis na pagkarga ng server at nagpapadala ng agarang alerto sa mga administrador sa Telegram.

5. Ikot ng Buhay ng File at Seguridad (GDPR)

Ang arkitektura ay idinisenyo sa modelo ng Zero-Data-Footprint:

  • Ang mga file ng gumagamit ay na-upload sa isang protektadong volume na tmp/conversions/ na may mga natatanging prefix batay sa mga identifier ng gawain.
  • Ang mga file ay nananatiling magagamit nang mahigpit sa loob ng sesyon ng trabaho — hindi hihigit sa 15 minuto (900 segundo).
  • Ang awtomatikong garbage collector ay binubura ang orihinal at handa nang mga file kaagad pagkatapos makumpirma ang matagumpay na pagpapadala sa chat o pagkatapos ng timeout ng session.
  • Ang database ng PostgreSQL ay hindi nag-imbak ng mga binary file o personal na teksto ng mga dokumento — ang mga na-anonymize na teknikal na metadata lamang (mga format, laki sa mga byte, oras ng pagpapatakbo, mga katayuan) ang naitala sa mga talahanayan.

6. Unibersal na REST API para sa mga Panlabas na Web Services

Ang serbisyo ay orihinal na idinisenyo bilang isang multi-platform backend. Kasama ng bot, gumagana ang isang ganap na protektadong programming interface para sa mga website (halimbawa, sa Django) at mga bot ng third-party:

  • GET /api/v1/formats — dynamic na JSON matrix ng mga magagamit na direksyon ng conversion, naka-synchronize sa mga setting ng Google Sheets.
  • POST /api/v1/convert — unibersal na endpoint na tumatanggap ng multipart/form-data (file, target na format, external client ID) at nagbabalik ng handa nang stream ng byte sa anyo ng direktang pag-download.
  • Pagpapahintulot sa pamamagitan ng Bearer token (WEBHOOK_REFRESH_TOKEN) na may proteksyon laban sa mga pag-atake sa oras sa pamamagitan ng secrets.compare_digest.

7. Control Panel at Observability (NiceGUI + AG Grid)

Ang pagsubaybay sa mga tagapagpahiwatig ng negosyo at kalagayan ng sistema ay dinala sa isang katutubong Single-Page control panel batay sa NiceGUI 2.x:

  • Mga interactive na talahanayan na AG Grid (v32+) na may mga custom na filter ng checkbox na istilo ng Excel (aggrid_filters.js).
  • Pagsubaybay sa mga pila, pagkaantala ng API provider at pag-ping sa PostgreSQL / Redis sa real time.
  • End-to-end na pagsala sa pamamagitan ng mga petsa na may tuluy-tuloy na pagsasama ng Metabase BI dashboard sa pamamagitan ng mga naka-sign na JWT token.