Сервис 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-токены.