د All File Converter خدمت د Python 3.12 عصري اسینکرونس سټیک پر بنسټ د یوې توزیع شوي او پراختیا وړ SaaS سیسټم په توګه ډیزاین شوی. معمارۍ په خپلواکو طبقو ویشل شوې ده: د شبکې پیښو اخیستل، د دندو تنظیم کول، د درنو بینري پروسو جلا اجرا کول او د تحلیلي برخه.

1. عمومي ټیکنالوژیک سټیک او د سیسټم معمارۍ

د پلاتفورم بنسټ د لوړ فعالیت (high-throughput)، د حافظې لږ تر لږه کارولو او د ناکامیو په وړاندې د محافظت په اصولو ولاړ دی:

  • Telegram Bot Framework: Aiogram 3.13، چې په Webhook حالت کې د پټو ټکنونو تصدیق او د پیغامونو د ژوند د دورې دودیزو فلټرونو سره کار کوي.
  • د ویب شلوټ او REST API: FastAPI د Uvicorn ASGI-سیرور پر بنسټ د بینري فایلونو د اسینکرونس سټریمینګ سپارلو (FileResponse) او د BackgroundTasks له لارې د شالید پاکولو سره.
  • د صفونو بروکر او کیش: Redis 7 (د Celery دندو مدیریت، د مسابقې حالت (race condition) څخه بندیزونه، د برټ فورس محافظت، د غونډو (sessions) کیش کول).
  • د شالید اجرا کونکی (Task Queue): Celery 5.4 د converter_worker په جلا کانټینر کې د کارګرانو د تخصیص شوي پول سره.
  • ډیټابیس: PostgreSQL 16 د SQLAlchemy 2.0 (asyncpg) ORM طبقې سره، د دوامداره اړیکو پول (20+10 overflow) او د ماتو شویو معاملاتو د اتوماتیک بیا هڅې (@db_retry) سره.
  • د شبکې برخه: د Middleware له لارې سرور ته د مستقیم IP لاسرسي بندولو سره د Cloudflare Zero Trust له لارې تونل کول.

2. اسینکرونس صفونه او د درنو محاسبو جلا کول (Celery + Redis)

د میډیا فایلونو او دفتر پاکټونو بدلول په CPU او RAM باندې سخت فشار راوړي. د دې لپاره چې په ټیلیګرام کې د راتلونکو پیغامونو پروسس کولو پروسه د درنو عملیاتو په ترڅ کې بنده نه شي، کلکه جلا کول پلي شوي دي:

  • په Redis کې د دندو سپارل: د فارمیټ په ټاکلو سره، د ټیلیګرام پروسسر د PROCESSING حالت سره په ډیټابیس کې دنده ثبتوي او د Celery له لارې tasks.execute_conversion صف ته دنده اچوي.
  • د کارګر جلا کانټینر: د بدلولو د توکیو اجرا کول په یوه جلا لینکس کانټینر کې د پروسس وخت او حافظې خپل محدودیت سره ترسره کیږي.
  • د ځنډ کنټرول او وخت حدونه (Timeouts): د بهرنیو توکیو غوښتنې د سخت وخت کنټرول سره په اسینکرونس شرایطو کې پوښل شوي دي (conversion_timeout_sec = 180). د حد له تیریدو سره، پروسه د proc.kill() له لارې په زور سره پای ته رسیږي، چې سرچینې ازادوي.
  • د باوري کیدو وړ Fallback: د Redis بروکر د لنډمهاله نه شتون په صورت کې، دنده په اتوماتیک ډول د محلي اسینکرونس ډیسپیچر لخوا نیول کیږي او کارونکي ته له کومې نیمګړتیا پرته مستقیم اجرا کیږي.

3. د ځانګړو بدلولو انجنونو پایپ لاین

د ډیټا د هر ډول لپاره ځانګړي کورني توکیو او کتابتونونه کارول کیږي:

  • اسناد او جدولونه (LibreOffice): بې سرې د دفتر کڅوړه (soffice --headless) د DOCX، XLSX، PPTX، RTF، ODT دقیق رینډرینګ لپاره په PDF یا متن فایلونو کې.
  • سټریمینګ آډیو او ویډیو (FFmpeg): د ویډیو کوډیکونو (H.264)، آډیو کوډیکونو (MP3، OGG Opus) څو تارونو (multi-threaded) سره بیا کوډ کول، د غږیزو لارو ایستل، د GIF تولید (Lanczos-فلټر) او د ټیلیګرام ویډیو پیغامونو مربع قطع کول (1:1).
  • د PDF لوړ سرعت پروسس (Poppler Utils): توکي pdftotext (په UTF-8 کې د فارمیټ شوي متن سمدستي ایستل) او pdftoppm (د LibreOffice د اضافي لګښتونو پرته په پکسل انځورونو کې د PDF مخ په مخ رینډرینګ).
  • د متن نوری پیژندنه (Tesseract OCR): په 40+ ژبو کې له سکینونو او عکسونو څخه د چاپ شوي متن عصبي شبکې ایستل.
  • رستري او وکتوري ګرافیک: کتابتونونه Pillow (د HEIC او AVIF فارمیټونو ملاتړ په شمول)، د وکتوري انځورونو لپاره CairoSVG او د ټیلیګرام متحرک سټیکرونو (.TGS) لپاره lottie.
  • کتابونه، زیرنو او فونټونه: انجن Calibre (ebook-convert)، د زیرنو پارسر pysubs2 (SRT, VTT, ASS, SSA) او د فونټونو کمپیلر fonttools (په WOF2 کې د Brotli کمپریشن).

4. د سرچینو مخنیوی کونکی محافظت (System Guard)

د حافظې د کمښت (OOM Killer) له امله د سرور د غورځیدو څخه د محافظت لپاره، د مخنیوي تشخیص خدمت System Guard پلي شوی دی. مخکې لدې چې فایل د پروسس لپاره ونیول شي، سیسټم د کورنۍ کلیدي میټریکونه معاینه کوي:

  • خلاصه عاجله حافظه (RAM): لږترلږه 500 MB خلاصه اندازه (guard_min_free_ram_mb).
  • په ډیسک کې ځای: په /tmp لارښود کې لږترلږه 2 GB خلاصه فضا (guard_min_free_disk_mb).
  • د دندو صف: د Celery صف د اوږدوالي محدودیت (له 20 څخه ډیر انتظار کونکي دندې نه).

د حدونو د تیریدو په صورت کې، خدمت په لنډمهاله توګه محافظت فعالوي (HTTP 503 / په چیټ کې پیغام)، چې د سرور د ډیر بار مخه نیسي او په ټیلیګرام کې مدیرانو ته سمدستي خبرتیا لیږي.

5. د فایلونو د ژوند دوره او امنیت (GDPR)

معمارۍ د Zero-Data-Footprint ماډل پر بنسټ ډیزاین شوې ده:

  • د کاروونکو فایلونه د دندو پیژندونکو پر بنسټ د ځانګړو مخکونیو سره په خوندي حجم tmp/conversions/ کې پورته کیږي.
  • فایلونه په کلکه د کاري غونډې په چوکاټ کې د لاسرسي وړ پاتې کیږي — له 15 دقیقو څخه زیات نه (900 ثانیې).
  • اتوماتیک کثافات راټولوونکی (Garbage Collector) اصلي او چمتو شوي فایلونه سمدلاسه وروسته له هغه پاکوي کله چې چیټ ته د بریالي لیږلو تایید ترلاسه شي یا د غونډې وخت پای ته ورسیږي.
  • د PostgreSQL ډیټابیس بینري فایلونه یا د اسنادو شخصي متنونه نه ساتي — په جدولونو کې یوازې د نوم نه لرونکي تخنیکي میټاډاټا ثبت کیږي (فارمیټونه، په بایټونو کې اندازې، د کار وخت، حالتونه).

6. د بهرنیو ویب خدماتو لپاره همغږی REST API

خدمت په اصل کې د څو پلاتفورم شالید په توګه ډیزاین شوی. د بوټ ترڅنګ د ویب سایټونو (د بیلګې په توګه، په Django کې) او د دریمې ډلې بوټانو لپاره بشپړ خوندي پروګرام انٹرفیس کار کوي:

  • GET /api/v1/formats — د شته بدلولو لارښوونو متحرک JSON-میټریکس، چې د ګوګل شیټونو ترتیباتو سره همغږی شوی دی.
  • POST /api/v1/convert — یو نړیوال پای ټکی، چې multipart/form-data مني (فایل، هدف فارمیټ، د بهرني پیرودونکي ID) او د مستقیم ډاونلوډ په بڼه د بایټونو چمتو سټریم ورکوي.
  • د secrets.compare_digest له لارې د وخت بریدونو په وړاندې محافظت سره د Bearer-ټکنونو (WEBHOOK_REFRESH_TOKEN) له لارې تایید.

7. د کنټرول پینل او Observability (NiceGUI + AG Grid)

د سوداګرۍ شاخصونو او د سیسټم حالت څارنه د NiceGUI 2.x پر بنسټ په اصلي Single-Page کنټرول پینل کې راښودل شوې ده:

  • د اکسل سټایل دودیز چیک باکس فلټرونو سره متقابل جدولونه AG Grid (v32+) (aggrid_filters.js).
  • په ریښتیني وخت کې د صفونو، د API چمتو کونکو ځنډونو او د PostgreSQL / Redis پینګ څارنه.
  • د لاسلیک شوي JWT ټکنونو له لارې د Metabase BI-داشبورد بې سیمه ادغام سره د نیټو له مخې جامع فلټر کول.