Сервисот 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, заклучувања од состојба на трка, заштита од брут-форс, кеширање сесии).
  • Позадински извршител (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 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 секунди).
  • Автоматскиот чистач на ѓубре ги брише оригиналните и готови фајлови веднаш по потврдата за успешно испраќање во чатот или по истекот на тајмаутот на сесијата.
  • Базата на податоци 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-стил (aggrid_filters.js).
  • Мониторинг на редици, доцнења на API-провајдерите и пинг на PostgreSQL / Redis во реално време.
  • Низводно филтрирање по датуми со беспрекорна интеграција на BI-контролната табла Metabase преку потпишани JWT-токени.