სერვისი All File Converter შექმნილია როგორც მასშტაბირებადი, განაწილებული SaaS-სისტემა თანამედროვე ასინქრონული Python 3.12 სტეკის ბაზაზე. არქიტექტურა დაყოფილია დამოუკიდებელ ფენებად: ქსელური მოვლენების მიღება, დავალებების ორკესტრაცია, მძიმე ბინარული პროცესების იზოლირებული შესრულება და ანალიტიკური კონტური.

1. ზოგადი ტექნოლოგიური სტეკი და სისტემური არქიტექტურა

პლატფორმის საფუძვლად ჩადებულია მაღალი წარმადობის (high-throughput), მეხსიერების მინიმალური მოხმარებისა და შეცდომებისგან დაცვის პრინციპები:

  • Telegram Bot Framework: Aiogram 3.13, რომელიც მუშაობს Webhook რეჟიმში საიდუმლო ტოკენების ვალიდაციით და შეტყობინებების სასიცოცხლო ციკლის მორგებული ფილტრებით.
  • ვებ-შლუზი და REST API: FastAPI Uvicorn ASGI-სერვერის ბაზაზე, ბინარული ფაილების ასინქრონული ნაკადოვანი გადაცემით (FileResponse) და ფონური გასუფთავებით BackgroundTasks-ის მეშვეობით.
  • რიგების ბროკერი და ქეში: Redis 7 (Celery-ის დავალებების მართვა, რბოლის მდგომარეობის (race condition) დაბლოკვები, ბრუტფორსისგან დაცვა, სესიების ქეშირება).
  • ფონური შემлულებელი (Task Queue): Celery 5.4 ვორკერების გამოყოფილი პულით იზოლირებულ converter_worker კონტეინერში.
  • მონაცემთა ბაზა: PostgreSQL 16 ORM ფენით SQLAlchemy 2.0 (asyncpg), მუდმივი კავშირების პულით (20+10 overflow) და წარუმატებელი ტრანზაქციების ავტომატური გამეორებით (@db_retry).
  • ქსელური კონტური: გვირაბირება (Tunneling) Cloudflare Zero Trust-ის გავლით Middleware-ის მეშვეობით სერვერთან პირდაპირი IP-წვდომის დაბლოკვით.

2. ასინქრონული რიგები და მძიმე გამოთვლების იზოლაცია (Celery + Redis)

მედიაფაილებისა და ოფისის პაკეტების კონვერტაცია ქმნის პიკურ დატვირთვას CPU-სა და RAM-ზე. იმისათვის, რომ Telegram-ში შემოსული შეტყობინებების დამუშავების პროცესი არ დაიბლოკოს მძიმე ოპერაციების დროს, დანერგილია მკაცრი იზოლაცია:

  • დავალებების დელეგირება Redis-ში: ფორმატის არჩევისას Telegram დამმუშავებელი აფიქსირებს დავალებას მონაცემთა ბაზაში სტატუსით PROCESSING და ათავსებს დავალებას tasks.execute_conversion რიგში Celery-ის გავლით.
  • ვორკერის იზოლირებული კონტეინერი: კონვერტაციის უტილიტების შესრულება ხდება ცალკეულ Linux კონტეინერში, რომელსაც გააჩნია პროცესორის დროისა და მეხსიერების საკუთარი ლიმიტი.
  • გაყინვების კონტროლი და ტაიმაუტები: გარე უტილიტების გამოძახებები მოქცეულია ასინქრონულ კონტექსტში დროის მკაცრი კონტროლით (conversion_timeout_sec = 180). ლიმიტის გადაჭარბებისას პროცესი იძულებით წყდება proc.kill()-ის მეშვეობით, რაც ათავისუფლებს რესურსებს.
  • მედეგი Fallback: Redis ბროკერის დროებითი მიუწვდომლობისას, დავალებას ავტომატურად იჭერს ლოკალური ასინქრონული დისპეტჩერი და ასრულებს პირდაპირ, მომხმარებლისთვის შეფერხების გარეშე.

3. სპეციალიზებული კონვერტაციის ძრავების კონვეიერი

მონაცემთა თითოეული ტიპისთვის გამოიყენება მკაცრად სპეციალიზებული ნატურალური უტილიტები და ბიბლიოთეკები:

  • დოკუმენტები და ცხრილები (LibreOffice): უთავო (headless) ოფისის პაკეტი (soffice --headless) DOCX, XLSX, PPTX, RTF, ODT ზუსტი რენდერინგისთვის PDF-ში ან ტექსტურ ფაილებში.
  • ნაკადოვანი აუდიო და ვიდეო (FFmpeg): ვიდეოკოდეკების (H.264), აუდიოკოდეკების (MP3, OGG Opus) მრავალნაკადოვანი გადაკოდირება, აუდიობილიკების ამოღება, GIF-ების გენერაცია (Lanczos-ფილტრი) და Telegram ვიდეოშეტყობინებების კვადრატული კადრირება (1:1).
  • PDF-ის მაღალსიჩქარიანი დამუშავება (Poppler Utils): უტილიტები pdftotext (დაფორმატებული ტექსტის მყისიერი ამოღება UTF-8-ში) და pdftoppm (PDF-ის გვერდ-გვერდ რენდერინგი რასტრულ სურათებში LibreOffice-ის ზედმეტი ხარჯების გარეშე).
  • ოპტიკური ამოცნობა (Tesseract OCR): დასკანერებული ფაილებიდან და ფოტოებიდან დაბეჭდილი ტექსტის ნეიროქსელური ამოღება 40+ ენაზე.
  • რასტრული და ვექტორული გრაფიკა: ბიბლიოთეკები Pillow (მათ შორის HEIC და AVIF ფორმატების მხარდაჭერა), CairoSVG ვექტორული სურათებისთვის და lottie Telegram-ის ანიმაციური სტიკერებისთვის (.TGS).
  • წიგნები, სუბტიტრები და შრიფტები: ძრავი Calibre (ebook-convert), სუბტიტრების პარსერი pysubs2 (SRT, VTT, ASS, SSA) და შრიფტების კომპილატორი fonttools (Brotli-კომპრესია WOFF2-ში).

4. რესურსების პრევენციული დაცვა (System Guard)

მეხსიერების უკმარისობის გამო (OOM Killer) სერვერის ჩამოვარდნისგან დასაცავად დანერგილია პრევენციული დიაგნოსტიკის სერვისი System Guard. ფაილის დამუშავებამდე მიღებამდე სისტემა ამოწმებს ჰოსტის საკვანძო მეტრიკებს:

  • თავისუფალი ოპერატიული მეხსიერება (RAM): მინიმუმ 500 მბ თავისუფალი მოცულობა (guard_min_free_ram_mb).
  • ადგილი დისკზე: მინიმუმ 2 გბ თავისუფალი სივრცე /tmp დირექტორიაში (guard_min_free_disk_mb).
  • დავალებების რიგი: Celery-ის რიგის სიგრძის შეზღუდვა (არაუმეტეს 20 მოლოდინის რეჟიმში მყოფი დავალებისა).

ლიმიტების გადაჭარბებისას სერვისი დროებით რრთავს დაცვას (HTTP 503 / შეტყობინება ჩატში), რაც თავიდან აიცილებს სერვერის გადატვირთვას და Telegram-ში მყისიერ ალერტს უგზავნის ადმინისტრატორებს.

5. ფაილების სასიცოცხლო ციკლი და უსაფრთხოება (GDPR)

არქიტექტურა დაპროექტებულია Zero-Data-Footprint მოდელით:

  • მომხმარებელთა ფაილები იტვირთება დაცულ ტომში tmp/conversions/ უნიკალური პრეფიქსებით, რომლებიც დაფუძნებულია დავალებების იდენტიფიკატორებზე.
  • ფაილები ხელმისაწვდომია მკაცრად სამუშაო სესიის ფარგლებში — არაუმეტეს 15 წუთისა (900 წამი).
  • ავტომატური ნაგვის შემგროვებელი (Garbage Collector) შლის საწყის და მზა ფაილებს ჩატში წარმატებული გაგზავნის დადასტურებისთანავე ან სესიის ტაიმაუტის ამოწურვისას.
  • PostgreSQL მონაცემთა ბაზა არ ინახავს ბინარულ ფაილებს ან დოკუმენტების პერსონალურ ტექსტებს — ცხრილებში ფიქსირდება მხოლოდ ანონიმური ტექნიკური მეტამონაცემები (ფორმატები, ზომები ბიტებში, მუშაობის დრო, სტატუსები).

6. უნივერსალური REST API გარე ვებ-სერვისებისთვის

სერვისი თავიდანვე დაპროექტებულია როგორც მულტიპლატფორმური ბექენდი. ბოტთან ერთად ფუნქციონირებს სრულფასოვანი დაცული პროგრამული ინტერფეისი ვებ-საიტებისთვის (მაგალითად, Django-ზე) და მესამე მხარის ბოტებისთვის:

  • GET /api/v1/formats — ხელმისაწვდომი კონვერტაციის მიმართულებების დინამიკური JSON-მატრიცა, სინქრონიზებული Google Sheets-ის პარამეტრებთან.
  • POST /api/v1/convert — უნივერსალური ენდპოინტი, რომელიც იღებს multipart/form-data (ფაილი, სამიზნე ფორმატი, გარე კლიენტის ID) და აბრუნებს მზა ბიტების ნაკადს (stream) პირდაპირი ჩამოტვირთვის სახით.
  • ავტორიზაცია Bearer ტოკენებით (WEBHOOK_REFRESH_TOKEN) დროითი შეტევებისგან დაცვით secrets.compare_digest-ის მეშვეობით.

7. მართვის პანელი და Observability (NiceGUI + AG Grid)

ბიზნეს-მაჩვენებლებისა და სისტემის მდგომარეობის მონიტორიнгი გამოტანილია ნატიურ Single-Page მართვის პანელში NiceGUI 2.x-ის ბაზაზე:

  • ინტერაქტიული ცხრილები AG Grid (v32+) მორგებული Excel-სტილის ჩექბოქს-ფილტრებით (aggrid_filters.js).
  • რიგების, API პროვაიდერების დაყოვნებების და PostgreSQL / Redis პინგის მონიტორიнгი რეალურ დროში.
  • გავლილი ფილტრაცია თარიღების მიხედვით Metabase BI დაშბორდის უწყვეტი ინტეგრაციით ხელმოწერილი JWT ტოკენების მეშვეობით.