All File Converter xidməti müasir Python 3.12 asinxron steki əsasında miqyaslana bilən paylanmış SaaS sistemi kimi layihələndirilmişdir. Arxitektura müstəqil təbəqələrə bölünür: şəbəkə hadisələrinin qəbulu, tapşırıqların orkestrləşdirilməsi, ağır ikili proseslərin izolyasiya edilmiş icrası və analitik dövrə.

1. Ümumi texnologiya steki və sistem arxitekturası

Platformanın əsasında yüksək məhsuldarlıq (high-throughput), minimal yaddaş sərfiyyatı və qəzalardan müdafiə prinsipləri dayanır:

  • Telegram Bot Framework: Məxfi tokenlərin doğrulanması (validation) və ismarıcların həyat dövrünün xüsusi filtrləri ilə Webhook rejimində işləyən Aiogram 3.13.
  • Veb-şлюз və REST API: Asinxron axınlı ikili fayl ötürülməsi (FileResponse) və BackgroundTasks vasitəsilə fon təmizlənməsi ilə Uvicorn ASGI serveri bazasında FastAPI.
  • Növbələr brokeri və kэş: Redis 7 (Celery tapşırıqlarının idarə edilməsi, yarış vəziyyətindən kilidlər, bruteforce-dan müdafiə, sessiyaların kэşlənməsi).
  • Fon icraçısı (Task Queue): İzolyasiya edilmiş converter_worker konteynerində xüsusi işçi hovuzu (worker pool) ilə Celery 5.4.
  • Verilənlər bazası: SQLAlchemy 2.0 (asyncpg) ORM təbəqəsi, daimi əlaqələr hovuzu (20+10 overflow) və uğursuz tranzaksiyaların avtomatik təkrarı (@db_retry) ilə PostgreSQL 16.
  • Şəbəkə dövrü: Middleware vasitəsilə birbaşa IP girişinin bloklandığı Cloudflare Zero Trust üzərindən tunelləşdirmə.

2. Asinxron növbələr və ağır hesabatların izolyasiyası (Celery + Redis)

Mediafaylların və ofis paketlərinin konvertasiyası CPU və RAM-a pik yüklər yaradır. Telegram-da daxil olan ismarıcların emal prosesinin ağır əməliyyatlar zamanı bloklanmaması üçün ciddi izolyasiya həyata keçirilmişdir:

  • Tapşırıqların Redis-ə ötürülməsi: Format seçildikdə Telegram-emalçı tapşırığı PROCESSING statusu ilə VB-də qeydiyyatdan keçirir və Celery vasitəsilə tasks.execute_conversion növbəsinə qoyur.
  • İşçinin izolyasiya edilmiş konteyneri: Konvertasiya utilitlərinin icrası prosessor vaxtı və yaddaş üzrə öz limitləri olan ayrı Linux konteynerində baş verir.
  • Donmaların nəzarəti və taym-aуtlar: Xarici utilitlərin çağırışları ciddi vaxt nəzarəti ilə asinxron kontekstə bükülmüşdür (conversion_timeout_sec = 180). Limit aşılarsa, proses proc.kill() vasitəsilə məcburi şəkildə sonlandırılır və resurslar azad edilir.
  • Dözümlü Fallback: Redis brokeri müvəqqəti əlçatmaz olduqda, tapşırıq avtomatik olaraq yerli asinxron dispetçer tərəfindən tutulur və istifadəçi üçün heç bir nasazlıq yaratmadan birbaşa yerinə yetirilir.

3. İxtisaslaşdırılmış konvertasiya mühərrikləri konveyeri

Hər bir məlumat növü üçün dar ixtisaslaşdırılmış nativ utilitlər və kitabxanalar cəlb olunur:

  • Sənədlər və cədvəllər (LibreOffice): DOCX, XLSX, PPTX, RTF, ODT fayllarını PDF formatına və ya mətn fayllarına dəqiq render etmək üçün başsız ofis paketi (soffice --headless).
  • Axın audio və videoları (FFmpeg): Videokodeklərin (H.264), audiokodeklərin (MP3, OGG Opus) çoxaxınlı yenidən kodlaşdırılması, səs izlərinin çıxarılması, GIF generasiyası (Lanczos filtri) və Telegram videomisajlarının kvadrat kadrlaşdırılması (1:1).
  • Yüksək sürətli PDF emalı (Poppler Utils): pdftotext (formatlaşdırılmış mətnin UTF-8-ə ani çıxarılması) və pdftoppm (LibreOffice əlavə xərcləri olmadan PDF-in səhifə-səhifə rastr təsvirlərə render edilməsi) utilitləri.
  • Optik tanınma (Tesseract OCR): 40+ dildə skanlardan və fotoşəkillərdən çap olunmuş mətnin neyron şəbəkə vasitəsilə çıxarılması.
  • Rastr və vektor qrafikası: Pillow kitabxanaları (HEIC və AVIF format dəstəyi daxil olmaqla), vektor təsvirlər üçün CairoSVG və animasiyalı Telegram stikerləri (.TGS) üçün lottie.
  • Kitablar, subtitrlər və şriftlər: Calibre mühərriki (ebook-convert), pysubs2 subtitr parseri (SRT, VTT, ASS, SSA) və fonttools şrift kompilyatoru (WOFF2-də Brotli kompressiyası).

4. Resursların qabaqlayıcı mühafizəsi (System Guard)

Yaddaş çatışmazlığı səbəbindən serverin çökçəsinin (OOM Killer) qarşısını almaq üçün System Guard qabaqlayıcı diaqnostika xidməti tətbiq edilmişdir. Fayl emala qəbul edilməzdən əvvəl sistem hostun əsas metrikalarını yoxlayır:

  • Sərbəst operativ yaddaş (RAM): Minimum 500 MB boş həcm (guard_min_free_ram_mb).
  • Diskdə yer: /tmp qovluğunda minimum 2 GB boş yer (guard_min_free_disk_mb).
  • Tapşırıqlar növbəsi: Celery növbə uzunluğunun məhdudlaşdırılması (20-dən çox gözləyən tapşırıq olmamalıdır).

Limitlər aşılarsa, xidmət müvəqqəti olaraq mühafizəni işə salır (HTTP 503 / çatda ismarıc), serverin həddindən artıq yüklənməsinin qarşısını alır və administratorlara Telegram-da ani xəbərdarlıq göndərir.

5. Faylların həyat dövrü və təhlükəsizlik (GDPR)

Arxitektura Zero-Data-Footprint modeli üzrə layihələndirilmişdir:

  • İstifadəçi faylları tapşırıqların identifikatorları əsasında unikal prefikslərlə tmp/conversions/ təhlükəsiz tomuna yüklənir.
  • Faydalar yalnız iş sessiyası çərçivəsində — 15 dəqiqədən çox olmayaraq (900 saniyə) əlçatan qalır.
  • Avtomatik zibil yığıcı (garbage collector) ilkin və hazır faylları çata uğurlu göndərilmə təsdiqindən dərhal sonra və ya sessiyanın taym-aуtu bitdikdən sonra silir.
  • PostgreSQL verilənlər bazası ikili faylları və ya sənədlərin fərdi mətnlərini saxlamır — cədvəllərdə yalnız anonimləşdirilmiş texniki metadlumatlar (formatlar, baytlarla ölçülər, iş vaxtı, statuslar) qeyd olunur.

6. Xarici veb-xidmətlər üçün universal REST API

Xidmət ilkin olaraq çoxplatformalı backend kimi layihələndirilmişdir. Botla yanaşı, veb-saytlar (məsələn, Django üzərində) və kənar botlar üçün tamhüquqlu təhlükəsiz proqram interfeysi fəaliyyət göstərir:

  • GET /api/v1/formats — Google Cədvəllərin ayarları ilə sinxronlaşdırılmış mövcud konvertasiya istiqamətlərinin dinamik JSON-matrisası.
  • POST /api/v1/convert — multipart/form-data (fayl, hədəf format, kənar müştərinin ID-si) qəbul edən və birbaşa yükləmə şəklində hazır bayt axını verən universal endpoint.
  • secrets.compare_digest vasitəsilə vaxt hücumlarından qorunan Bearer tokenləri ilə avtorizasiya (WEBHOOK_REFRESH_TOKEN).

7. İdarəetmə paneli və Observability (NiceGUI + AG Grid)

Biznes göstəricilərinin və sistemin vəziyyətinin monitorinqi NiceGUI 2.x bazasında nativ Single-Page idarəetmə panelinə çıxarılmışdır:

  • Xüsusi Excel-style checkbox filtrləri ilə interaktiv AG Grid (v32+) cədvəlləri (aggrid_filters.js).
  • Real vaxt rejimində növbələrin, API-provayderlərin gecikmələrinin və PostgreSQL / Redis pinqinin monitorinqi.
  • İmzalanmış JWT tokenləri vasitəsilə Metabase BI-daşbordinin qüsursuz inteqrasiyası ilə tarixlər üzrə qapalı filtrasiya.