Layanan All File Converter dirancang sebagai sistem SaaS terdistribusi yang dapat disesuaikan (skalabel) berbasis tumpukan asinkron modern Python 3.12. Arsitektur ini dibagi menjadi lapisan-lapisan independen: penerimaan event jaringan, orkestrasi tugas, eksekusi proses biner berat secara terisolasi, dan siklus analitik.

1. Tumpukan Teknologi Umum dan Arsitektur Sistem

Platform ini didasarkan pada prinsip kinerja tinggi (high-throughput), konsumsi memori minimum, dan perlindungan terhadap kegagalan:

  • Telegram Bot Framework: Aiogram 3.13, beroperasi dalam mode Webhook dengan validasi token rahasia dan filter siklus hidup pesan kustom.
  • Gateway Web dan REST API: FastAPI berbasis server ASGI Uvicorn dengan pengiriman stream file biner asinkron (FileResponse) dan pembersihan latar belakang melalui BackgroundTasks.
  • Broker Antrean dan Cache: Redis 7 (manajemen tugas Celery, penguncian dari race condition, perlindungan terhadap brute force, caching sesi).
  • Eksekutor Latar Belakang (Task Queue): Celery 5.4 dengan kumpulan worker khusus dalam container terisolasi converter_worker.
  • Database: PostgreSQL 16 dengan lapisan ORM SQLAlchemy 2.0 (asyncpg), pool koneksi permanen (20+10 overflow), dan pengulangan otomatis transaksi yang gagal (@db_retry).
  • Sirkuit Jaringan: Tunneling melalui Cloudflare Zero Trust dengan pemblokiran akses IP langsung ke server melalui Middleware.

2. Antrean Asinkron dan Isolasi Komputasi Berat (Celery + Redis)

Konversi file media dan paket perkantoran menciptakan beban puncak pada CPU dan RAM. Agar proses pemrosesan pesan masuk di Telegram tidak terhalang oleh operasi berat, isolasi ketat telah diterapkan:

  • Pendelegasian Tugas ke Redis: Saat memilih format, handler Telegram mendaftarkan tugas ke database dengan status PROCESSING dan menempatkan tugas ke dalam antrean tasks.execute_conversion melalui Celery.
  • Container Worker Terisolasi: Eksekusi utilitas konversi terjadi di container Linux terpisah dengan batas waktu prosesor dan memori sendiri.
  • Kontrol Pembekuan dan Timeout: Pemanggilan utilitas eksternal dibungkus dalam konteks asinkron dengan kontrol waktu yang ketat (conversion_timeout_sec = 180). Jika batas terlampaui, proses dihentikan secara paksa melalui proc.kill(), melepaskan sumber daya.
  • Fallback Tahan Kesalahan: Jika broker Redis sementara tidak tersedia, tugas akan secara otomatis dicegat oleh dispatcher asinkron lokal dan dieksekusi secara langsung tanpa gangguan bagi pengguna.

3. Pipeline Mesin Konversi Khusus

Untuk setiap jenis data, utilitas dan pustaka asli yang sangat khusus digunakan:

  • Dokumen dan Tabel (LibreOffice): Paket perkantoran tanpa kepala (soffice --headless) untuk rendering akurat DOCX, XLSX, PPTX, RTF, ODT ke format PDF atau file teks.
  • Audio dan Video Streaming (FFmpeg): Transcoding multi-thread untuk codec video (H.264), codec audio (MP3, OGG Opus), ekstraksi jalur suara, pembuatan GIF (filter Lanczos), dan pemotongan kotak (1:1) pesan video Telegram.
  • Pemrosesan PDF Kecepatan Tinggi (Poppler Utils): Utilitas pdftotext (ekstraksi instan teks terformat dalam UTF-8) dan pdftoppm (rendering halaman PDF ke gambar raster tanpa overhead LibreOffice).
  • Pengenalan Optik (Tesseract OCR): Ekstraksi teks cetak berbasis jaringan saraf dari pindaian dan foto dalam 40+ bahasa.
  • Grafik Raster dan Vektor: Pustaka Pillow (termasuk dukungan untuk format HEIC dan AVIF), CairoSVG untuk gambar vektor, dan lottie untuk stiker animasi Telegram (.TGS).
  • Buku, Subtitle, dan Font: Mesin Calibre (ebook-convert), parser subtitle pysubs2 (SRT, VTT, ASS, SSA), dan compiler font fonttools (kompresi Brotli di WOFF2).

4. Perlindungan Sumber Daya Preventif (System Guard)

Untuk melindungi dari crash server karena kekurangan memori (OOM Killer), layanan diagnostik preventif System Guard telah diterapkan. Sebelum menerima file untuk diproses, sistem memeriksa metrik host utama:

  • Memori Akses Acak Bebas (RAM): Minimum 500 MB volume bebas (guard_min_free_ram_mb).
  • Ruang Disk: Minimum 2 GB ruang kosong di direktori /tmp (guard_min_free_disk_mb).
  • Antrean Tugas: Batasan panjang antrean Celery (tidak lebih dari 20 tugas yang menunggu).

Jika batas terlampaui, layanan akan sementara mengaktifkan perlindungan (HTTP 503 / pesan di chat), mencegah kelebihan beban server dan mengirimkan peringatan instan kepada administrator di Telegram.

5. Siklus Hidup File dan Keamanan (GDPR)

Arsitektur ini dirancang dengan model Zero-Data-Footprint:

  • File pengguna diunggah ke volume aman tmp/conversions/ dengan awalan unik berdasarkan pengenal tugas.
  • File tetap dapat diakses secara ketat dalam kerangka sesi kerja — tidak lebih dari 15 menit (900 detik).
  • Garbage collector otomatis menghapus file sumber dan file yang sudah jadi segera setelah konfirmasi pengiriman berhasil ke chat atau setelah waktu habis sesi berakhir.
  • Database PostgreSQL tidak menyimpan file biner atau teks dokumen pribadi — tabel hanya mencatat metadata teknis yang dianomimkan (format, ukuran dalam byte, waktu proses, status).

6. REST API Universal untuk Layanan Web Eksternal

Layanan ini awalnya dirancang sebagai backend multi-platform. Seiring dengan bot, antarmuka pemrograman terlindungi yang berfungsi penuh beroperasi untuk situs web (misalnya, di Django) dan bot pihak ketiga:

  • GET /api/v1/formats — matriks JSON dinamis dari arah konversi yang tersedia, disinkronkan dengan pengaturan Google Sheets.
  • POST /api/v1/convert — endpoint universal yang menerima multipart/form-data (file, format target, ID klien eksternal) dan memberikan aliran byte yang siap sebagai unduhan langsung.
  • Otorisasi menggunakan token Bearer (WEBHOOK_REFRESH_TOKEN) dengan perlindungan terhadap serangan waktu melalui secrets.compare_digest.

7. Panel Kontrol dan Observability (NiceGUI + AG Grid)

Pemantauan indikator bisnis dan status sistem telah dimasukkan ke dalam panel kontrol Single-Page asli berbasis NiceGUI 2.x:

  • Tabel interaktif AG Grid (v32+) dengan filter kotak centang gaya Excel kustom (aggrid_filters.js).
  • Pemantauan antrean, latensi penyedia API, dan ping PostgreSQL / Redis secara real-time.
  • Pemfilteran end-to-end berdasarkan tanggal dengan integrasi mulus dasbor BI Metabase melalui token JWT yang ditandatangani.