Сервіс All File Converter спроєктований як масштабована розподілена SaaS-система на базі сучасного асинхронного стека Python 3.12. Архітектура розділена на незалежні шари: прийом мережевих подій, оркестрація завдань, ізольоване виконання важких бінарних процесів та аналітичний контур.

1. Загальний стек технологій та системна архітектура

В основу платформи закладено принципи високої продуктивності (high-throughput), мінімального споживання пам'яті та захисту від збоїв:

  • Telegram Bot Framework: Aiogram 3.13, що працює в режимі Webhook з валідацією секретних токенів та кастомними фільтрами життєвого циклу повідомлень.
  • Вебшлюз та REST API: FastAPI на базі ASGI-сервера Uvicorn з асинхронною потоковою видачею бінарних файлів (FileResponse) та фоновим очищенням через BackgroundTasks.
  • Брокер черг та кеш: Redis 7 (керування завданнями Celery, блокування від стану гонки, захист від брутфорсу, кешування сесій).
  • Фоновий виконавець (Task Queue): Celery 5.4 з виділеним пулом воркерів в ізольованому контейнері converter_worker.
  • База даних: PostgreSQL 16 з ORM-шаром SQLAlchemy 2.0 (asyncpg), пулом постійних з'єднань (20+10 overflow) та автоповтором збійних транзакцій (@db_retry).
  • Мережевий контур: Тунелювання через Cloudflare Zero Trust з блокуванням прямого IP-доступу до сервера через Middleware.

2. Асинхронні черги та ізоляція важких обчислень (Celery + Redis)

Конвертація медіафайлів та офісних пакетів створює пікові навантаження на CPU та RAM. Щоб процес обробки вхідних повідомлень у Telegram не блокувався під час важких операцій, реалізовано сувору ізоляцію:

  • Делегування завдань у Redis: При виборі формату Telegram-обробник реєструє завдання в БД зі статусом PROCESSING та ставить завдання в чергу tasks.execute_conversion через Celery.
  • Ізольований контейнер воркера: Виконання утиліт конвертації відбувається в окремому Linux-контейнері з власним лімітом процесорного часу та пам'яті.
  • Контроль зависань та таймаути: Виклики зовнішніх утиліт обгорнуті в асинхронний контекст із жорстким контролем часу (conversion_timeout_sec = 180). У разі перевищення ліміту процес примусово завершується через proc.kill(), звільняючи ресурси.
  • Відмовостійкий Fallback: У разі тимчасової недоступності брокера Redis завдання автоматично перехоплюється локальним асинхронним диспетчером і виконується напряму без збою для користувача.

3. Конвеєр спеціалізованих двигунів конвертації

Для кожного типу даних задіюються вузькоспеціалізовані нативні утиліти та бібліотеки:

  • Документи та таблиці (LibreOffice): Безголовий офісний пакет (soffice --headless) для точного рендерингу DOCX, XLSX, PPTX, RTF, ODT у формат PDF або текстові файли.
  • Потокове аудіо та відео (FFmpeg): Багатопотокове перекодування відеокодеків (H.264), аудіокодеків (MP3, OGG Opus), вилучення звукових доріжок, генерація GIF (Lanczos-фільтр) та квадратне кадрування (1:1) відеоповідомлень Telegram.
  • Високошвидкісна обробка 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 секунд).
  • Автоматичний збирач сміття стирає вихідні та готові файли одразу після підтвердження успішного надсилання в чат або після закінчення тайм-ауту сесії.
  • База даних PostgreSQL не зберігає бінарні файли чи персональні тексти документів — у таблицях фіксуються лише анонімізовані технічні метадані (формати, розміри в байтах, час роботи, статуси).

6. Універсальний REST API для зовнішніх вебсервісів

Сервіс від початку спроєктований як мультиплатформний бекенд. Поряд із ботом функціонує повноцінний захищений програмний інтерфейс для вебсайтів (наприклад, на Django) та сторонніх ботів:

  • GET /api/v1/formats — динамічна JSON-матриця доступних напрямків конвертації, синхронізована з налаштуваннями Google Таблиць.
  • POST /api/v1/convert — універсальний ендпоїнт, що приймає multipart/form-data (файл, цільовий формат, ID зовнішнього клієнта) та віддає готовий потік байтів у вигляді прямого завантаження.
  • Авторизація за Bearer-токенами (WEBHOOK_REFRESH_TOKEN) із захистом від атак за часом через secrets.compare_digest.

7. Панель керування та Observability (NiceGUI + AG Grid)

Моніторинг бізнес-показників та стану системи виведено в нативну Single-Page панель керування на базі NiceGUI 2.x:

  • Інтерактивні таблиці AG Grid (v32+) з кастомними Excel-style чекбокс-фільтрами (aggrid_filters.js).
  • Моніторинг черг, затримок API-провайдерів та пінгу PostgreSQL / Redis у реальному часі.
  • Наскрізна фільтрація за датами з безшовною інтеграцією BI-дашборда Metabase через підписані JWT-токени.