Serwis All File Converter został zaprojektowany jako skalowalny, rozproszony system SaaS oparty na nowoczesnym asynchronicznym stosie Python 3.12. Architektura jest podzielona na niezależne warstwy: przyjmowanie zdarzeń sieciowych, orkiestrację zadań, izolowane wykonywanie ciężkich procesów binarnych oraz obwód analityczny.

1. Ogólny stos technologii i architektura systemu

Podstawą platformy są zasady wysokiej wydajności (high-throughput), minimalnego zużycia pamięci i ochrony przed awariami:

  • Telegram Bot Framework: Aiogram 3.13, działający w trybie Webhook z walidacją tokenów bezpieczeństwa i niestandardowymi filtrami cyklu życia wiadomości.
  • Brama webowa i REST API: FastAPI oparte na serwerze ASGI Uvicorn z asynchronicznym strumieniowym przesyłaniem plików binarnych (FileResponse) i czyszczeniem w tle przez BackgroundTasks.
  • Broker kolejek i pamięć podręczna: Redis 7 (zarządzanie zadaniami Celery, blokady przed wyścigami, ochrona przed bruteforce, buforowanie sesji).
  • Wykonawca w tle (Task Queue): Celery 5.4 z wydzieloną pulą workerów w izolowanym kontenerze converter_worker.
  • Baza danych: PostgreSQL 16 z warstwą ORM SQLAlchemy 2.0 (asyncpg), pulą stałych połączeń (20+10 overflow) i automatycznym ponawianiem nieudanych transakcji (@db_retry).
  • Obwód sieciowy: Tunelowanie przez Cloudflare Zero Trust z blokowaniem bezpośredniego dostępu IP do serwera za pomocą Middleware.

2. Asynchroniczne kolejki i izolacja ciężких obliczeń (Celery + Redis)

Konwersacja plików multimedialnych i pakietów biurowych generuje szczytowe obciążenia procesora i pamięci RAM. Aby proces przetwarzania wiadomości przychodzących w Telegram nie był blokowany podczas operacji o dużym obciążeniu, wdrożono ścisłą izolację:

  • Delegowanie zadań do Redis: Podczas wyboru formatu handler Telegrama rejestruje zadanie w bazie danych ze statusem PROCESSING i umieszcza zadanie w kolejce tasks.execute_conversion poprzez Celery.
  • Izolowany kontener workera: Wykonywanie narzędzi konwersacji odbywa się w osobnym kontenerze Linux z własnym limitem czasu procesora i pamięci.
  • Kontrola zawieszeń i limity czasu: Wywołania narzędzi zewnętrznych są owinięte w asynchroniczny kontekst z ścisłą kontrolą czasu (conversion_timeout_sec = 180). Po przekroczeniu limitu proces jest siłowo kończony przez proc.kill(), zwalniając zasoby.
  • Odporny na awarie Fallback: W przypadku tymczasowej niedostępności brokera Redis, zadanie jest automatycznie przejmowane przez lokalny dispatcher asynchroniczny i wykonywane bezpośrednio bez zakłóceń dla użytkownika.

3. Pipeline wyspecjalizowanych silników konwersacji

Dla każdego typu danych wykorzystywane są wysokowyspecjalizowane natywne narzędzia i biblioteki:

  • Dokumenty i arkusze (LibreOffice): Pakiet biurowy bez interfejsu graficznego (soffice --headless) do precyzyjnego renderowania DOCX, XLSX, PPTX, RTF, ODT do formatu PDF lub plików tekstowych.
  • Strumieniowe audio i wideo (FFmpeg): Wielowątkowe transkodowanie kodeków wideo (H.264), audio (MP3, OGG Opus), wyodrębnianie ścieżek dźwiękowych, generowanie GIF (filtr Lanczosa) i kwadratowe kadrowanie (1:1) wiadomości wideo Telegram.
  • Wysokowydajne przetwarzanie PDF (Poppler Utils): Narzędzia pdftotext (błyskawiczne wyodrębnianie sformatowanego tekstu w UTF-8) oraz pdftoppm (stronicowe renderowanie PDF do obrazów rastrowych bez narzutu LibreOffice).
  • Optyczne rozpoznawanie znaków (Tesseract OCR): Sieć neuronowa do wyodrębniania tekstu drukowanego ze skanów i zdjęć w ponad 40 językach.
  • Grafika rastrowa i wektorowa: Biblioteki Pillow (w tym obsługa formatów HEIC i AVIF), CairoSVG dla grafik wektorowych oraz lottie dla animowanych naklejek Telegram (.TGS).
  • Książki, napisy i czcionki: Silnik Calibre (ebook-convert), parser napisów pysubs2 (SRT, VTT, ASS, SSA) oraz kompilator czcionek fonttools (kompresja Brotli do WOFF2).

4. Prewencyjna ochrona zasobów (System Guard)

Aby chronić serwer przed awarią z powodu braku pamięci (OOM Killer), wdrożono serwis diagnostyki prewencyjnej System Guard. Przed przyjęciem pliku do przetworzenia system sprawdza kluczowe metryki hosta:

  • Wolna pamięć operacyjna (RAM): Minimum 500 MB wolnej przestrzeni (guard_min_free_ram_mb).
  • Miejsce na dysku: Minimum 2 GB wolnej przestrzeni w katalogu /tmp (guard_min_free_disk_mb).
  • Kolejka zadań: Ograniczenie długości kolejki Celery (nie więcej niż 20 oczekujących zadań).

Po przekroczeniu limitów serwis tymczasowo włącza ochronę (HTTP 503 / komunikat na czacie), zapobiegając przeciążeniu serwera i wysyłając natychmiastowy alert do administratorów w Telegram.

5. Cykl życia plików i bezpieczeństwo (GDPR)

Architektura została zaprojektowana zgodnie z modelem Zero-Data-Footprint:

  • Pliki użytkowników są przesyłane do zabezpieczonego wolumenu tmp/conversions/ z unikalnymi prefiksami opartymi na identyfikatorach zadań.
  • Pliki pozostają dostępne ściśle w ramach sesji roboczej — nie dłużej niż 15 minut (900 sekund).
  • Automatyczny moduł zbierający śmieci usuwa pliki oryginalne i gotowe natychmiast po potwierdzeniu pomyślnego wysłania na czat lub po wygaśnięciu limitu czasu sesji.
  • Baza danych PostgreSQL nie przechowuje plików binarnych ani poufnych tekstów dokumentów — w tabelach zapisywane są wyłącznie zanonimizowane metadane techniczne (formaty, rozmiary w bajtach, czas działania, statusy).

6. Uniwersalne REST API dla zewnętrznych serwisów webowych

Serwis od początku został zaprojektowany jako backend wieloplatformowy. Oprócz bota funkcjonuje w pełni zabezpieczony interfejs programistyczny dla stron internetowych (np. w Django) oraz botów zewnętrznych:

  • GET /api/v1/formats — dynamiczna macierz JSON dostępnych kierunków konwersacji, zsynchronizowana z ustawieniami Arkuszy Google.
  • POST /api/v1/convert — uniwersalny endpoint przyjmujący multipart/form-data (plik, format docelowy, ID klienta zewnętrznego) i zwracający gotowy strumień bajtów w formie bezpośredniego pobierania.
  • Autoryzacja za pomocą tokenów Bearer (WEBHOOK_REFRESH_TOKEN) z ochroną przed atakami czasowymi poprzez secrets.compare_digest.

7. Panel sterowania i Observability (NiceGUI + AG Grid)

Monitorowanie wskaźników biznesowych i stanu systemu zostało przeniesione do natywnego panelu Single-Page oparteго na NiceGUI 2.x:

  • Interaktywne tabele AG Grid (v32+) z niestandardowymi filtrami w stylu Excela (aggrid_filters.js).
  • Monitorowanie kolejek, opóźnień dostawców API oraz pingu PostgreSQL / Redis w czasie rzeczywistym.
  • Kompleksowe filtrowanie po datach z płynną integracją pulpitu BI Metabase poprzez podpisane tokeny JWT.