All File Converter servisi, modern Python 3.12 asenkron yığını tabanlı, ölçeklenebilir ve dağıtık bir SaaS sistemi olarak tasarlanmıştır. Mimari bağımsız katmanlara ayrılmıştır: ağ olaylarının kabulü, görev düzenlemesi, ağır ikili süreçlerin izole edilmiş yürütülmesi ve analitik devre.

1. Genel teknoloji yığını ve sistem mimarisi

Platformun temeli, yüksek performans (high-throughput), minimum bellek tüketimi ve arıza koruması prensiplerine dayanmaktadır:

  • Telegram Bot Framework: Gizli token doğrulaması ve özel mesaj yaşam döngüsü filtreleriyle Webhook modunda çalışan Aiogram 3.13.
  • Web ağ geçidi ve REST API: Asenkron akışlı ikili dosya sunumu (FileResponse) ve BackgroundTasks ile arka plan temizliği içeren ASGI sunucusu Uvicorn tabanlı FastAPI.
  • Kuyruk brokeri ve önbellek: Redis 7 (Celery görev yönetimi, yarış durumu kilitlemeleri, brute-force koruması, oturum önbellekleme).
  • Arka plan yürütücüsü (Task Queue): İzole converter_worker konteynerinde özel bir işçi havuzuna sahip Celery 5.4.
  • Veritabanı: SQLAlchemy 2.0 (asyncpg) ORM katmanı, kalıcı bağlantı havuzu (20+10 overflow) ve hatalı işlemler için otomatik yeniden deneme (@db_retry) özellikli PostgreSQL 16.
  • Ağ çevresi: Middleware aracılığıyla sunucuya doğrudan IP erişimi engellenmiş şekilde Cloudflare Zero Trust üzerinden tünelleme.

2. Asenkron kuyruklar ve ağır hesaplamaların izolasyonu (Celery + Redis)

Medya dosyalarının ve ofis paketlerinin dönüştürülmesi, CPU ve RAM üzerinde yoğun yük oluşturur. Telegram'daki gelen mesajların işlenme sürecinin ağır işlemler sırasında bloke olmaması için sıkı bir izolasyon uygulanmıştır:

  • Görevlerin Redis'e devredilmesi: Format seçildiğinde Telegram işleyicisi görevi PROCESSING durumuyla veritabanına kaydeder ve Celery aracılığıyla görevi tasks.execute_conversion kuyruğuna ekler.
  • İzole işçi konteyneri: Dönüştürme araçlarının çalıştırılması, kendi işlemci zamanı ve bellek sınırına sahip ayrı bir Linux konteynerinde gerçekleştirilir.
  • Donma kontrolü ve zaman aşırımları: Harici araç çağrıları, katı zaman kontrolüne sahip asenkron bir bağlamla sarılmıştır (conversion_timeout_sec = 180). Sınır aşıldığında süreç proc.kill() ile zorla sonlandırılır ve kaynaklar serbest bırakılır.
  • Hataya dayanıklı Fallback: Redis broker'ın geçici olarak erişilememesi durumunda görev, yerel asenkron yönetici tarafından otomatik olarak devralınır ve kullanıcı için herhangi bir kesinti olmaksızın doğrudan yürütülür.

3. Özelleştirilmiş dönüştürme motorları hattı

Her veri tipi için son derece uzmanlaşmış yerel araçlar ve kütüphaneler kullanılır:

  • Belgeler ve tablolar (LibreOffice): DOCX, XLSX, PPTX, RTF, ODT dosyalarının PDF'e veya metin dosyalarına doğru bir şekilde oluşturulması için başsız ofis paketi (soffice --headless).
  • Akışlı ses ve video (FFmpeg): Video codec bileşenlerinin (H.264), ses codec bileşenlerinin (MP3, OGG Opus) çok iş parçacıklı yeniden kodlanması, ses kanallarının çıkarılması, GIF oluşturma (Lanczos filtresi) ve Telegram video mesajlarının kare kırpılması (1:1).
  • Yüksek hızlı PDF işleme (Poppler Utils): pdftotext (UTF-8 biçimlendirilmiş metnin anında çıkarılması) ve pdftoppm (LibreOffice ek yükü olmadan PDF'lerin sayfa sayfa raster görüntülere dönüştürülmesi) araçları.
  • Optik Karakter Tanıma (Tesseract OCR): Taramalardan ve fotoğraflardan 40+ dilde basılı metnin sinir ağı ile çıkarılması.
  • Raster ve vektör grafikleri: Pillow kütüphaneleri (HEIC ve AVIF format desteği dahil), vektör görseller için CairoSVG ve Telegram animasyonlu çıkartmaları (.TGS) için lottie.
  • Kitaplar, altyazılar ve yazı tipleri: Calibre motoru (ebook-convert), pysubs2 altyazı ayrıştırıcısı (SRT, VTT, ASS, SSA) ve fonttools yazı tipi derleyicisi (WOFF2'de Brotli sıkıştırması).

4. Önleyici kaynak koruması (System Guard)

Bellek yetersizliği (OOM Killer) nedeniyle sunucunun çökmesini önlemek için System Guard önleyici tanılama servisi entegre edilmiştir. Sistem, bir dosyayı işlemeye almadan önce ana bilgisayarın temel metriklerini kontrol eder:

  • Boş RAM (RAM): Minimum 500 MB boş alan (guard_min_free_ram_mb).
  • Disk alanı: /tmp dizininde minimum 2 GB boş alan (guard_min_free_disk_mb).
  • Görev kuyruğu: Celery kuyruk uzunluğu sınırı (20'den fazla bekleyen görev olmaması).

Sınırlar aşıldığında servis geçici olarak korumayı etkinleştirir (HTTP 503 / sohbette mesaj), sunucu aşırı yüklenmesini önler ve Telegram'daki yöneticilere anında bir uyarı gönderir.

5. Dosya yaşam döngüsü ve güvenlik (GDPR)

Mimari, Sıfır Veri Ayak İzi (Zero-Data-Footprint) modeline göre tasarlanmıştır:

  • Kullanıcı dosyaları, görev tanımlayıcılarına dayalı benzersiz öneklerle güvenli bir tmp/conversions/ birimine yüklenir.
  • Dosyalar kesinlikle çalışma oturumu çerçevesinde — en fazla 15 dakika (900 saniye) boyunca erişilebilir kalır.
  • Otomatik çöp toplayıcı, sohbete başarılı gönderim onaylandıktan hemen sonra veya oturum zaman aşımı süresi dolduğunda orijinal ve hazır dosyaları siler.
  • PostgreSQL veritabanı ikili dosyaları veya belgelerin kişisel metinlerini saklamaz; tablolarda yalnızca anonimleştirilmiş teknik meta veriler (formatlar, bayt cinsinden boyutlar, çalışma süresi, durumlar) kaydedilir.

6. Harici web servisleri için evrensel REST API

Servis, başlangıçtan itibaren çok platformlu bir arka uç olarak tasarlanmıştır. Botun yanı sıra, web siteleri (örneğin Django tabanlı) ve üçüncü taraf botlar için tam teşekküllü güvenli bir programlama arayüzü çalışmaktadır:

  • GET /api/v1/formats — Google E-Tablolar ayarlarıyla senkronize edilmiş, mevcut dönüştürme yönlerinin dinamik JSON matrisi.
  • POST /api/v1/convert — multipart/form-data (dosya, hedef format, harici istemci ID) kabul eden ve doğrudan indirme şeklinde hazır bayt akışı döndüren evrensel uç nokta.
  • secrets.compare_digest aracılığıyla zaman saldırılarına karşı korumalı Bearer token yetkilendirmesi (WEBHOOK_REFRESH_TOKEN).

7. Kontrol paneli ve Observability (NiceGUI + AG Grid)

İşletme göstergelerinin ve sistem durumunun izlenmesi, NiceGUI 2.x tabanlı yerel bir Tek Sayfalı (Single-Page) kontrol paneline taşınmıştır:

  • Özel Excel tarzı onay kutusu filtrelerine sahip interaktif AG Grid (v32+) tabloları (aggrid_filters.js).
  • Kuyrukların, API sağlayıcı gecikmelerinin ve PostgreSQL / Redis ping'lerinin gerçek zamanlı izlenmesi.
  • İmzalanmış JWT tokenleri aracılığıyla Metabase BI panosunun kesintisiz entegrasyonu ile tarihe göre uçtan uca filtreleme.