Услугата 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, блокировки срещу състезателни условия (race conditions), защита срещу брутфорс, кеширане на сесии).
  • Фонов изпълнител (Task Queue): Celery 5.4 с отделен пул от уоркърi в изолиран контейнер 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 MB свободен обем (guard_min_free_ram_mb).
  • Дисково пространство: Минимум 2 GB свободно пространство в директорията /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 Таблици.
  • 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 за квадратчета за отметка (checkbox) (aggrid_filters.js).
  • Мониторинг на опашки, закъснения на API доставчици и пинг на PostgreSQL / Redis в реално време.
  • Пълноценно филтриране по дати с безшевна интеграция на BI табло Metabase чрез подписани JWT токени.