The All File Converter service is designed as a scalable distributed SaaS system based on a modern asynchronous Python 3.12 stack. The architecture is divided into independent layers: network event ingestion, task orchestration, isolated execution of heavy binary processes, and an analytical pipeline.

1. General Technology Stack and System Architecture

The platform is built on the principles of high throughput, minimal memory consumption, and fault tolerance:

  • Telegram Bot Framework: Aiogram 3.13, operating in Webhook mode with secret token validation and custom message lifecycle filters.
  • Web Gateway and REST API: FastAPI based on the Uvicorn ASGI server with asynchronous binary file streaming (FileResponse) and background cleanup via BackgroundTasks.
  • Queue Broker and Cache: Redis 7 (Celery task management, race condition locks, brute-force protection, session caching).
  • Background Task Executor (Task Queue): Celery 5.4 with a dedicated pool of workers in an isolated converter_worker container.
  • Database: PostgreSQL 16 with the SQLAlchemy 2.0 (asyncpg) ORM layer, a persistent connection pool (20+10 overflow), and automatic retry for failed transactions (@db_retry).
  • Network Perimeter: Tunneling via Cloudflare Zero Trust with direct IP access to the server blocked via Middleware.

2. Asynchronous Queues and Heavy Computation Isolation (Celery + Redis)

Media file and office suite conversion creates peak loads on CPU and RAM. To prevent incoming Telegram message processing from being blocked during heavy operations, strict isolation is implemented:

  • Task Delegation to Redis: Upon format selection, the Telegram handler registers the task in the database with the PROCESSING status and queues the job in tasks.execute_conversion via Celery.
  • Isolated Worker Container: Conversion utilities are executed in a separate Linux container with its own CPU time and memory limits.
  • Freeze Control and Timeouts: External utility calls are wrapped in an asynchronous context with strict time control (conversion_timeout_sec = 180). If the limit is exceeded, the process is forcefully terminated via proc.kill(), freeing up resources.
  • Fault-Tolerant Fallback: In the event of a temporary Redis broker outage, the task is automatically intercepted by the local asynchronous dispatcher and executed directly without disrupting the user.

3. Specialized Conversion Engine Pipeline

Highly specialized native utilities and libraries are employed for each data type:

  • Documents and Spreadsheets (LibreOffice): A headless office suite (soffice --headless) for accurate rendering of DOCX, XLSX, PPTX, RTF, and ODT into PDF or text files.
  • Streaming Audio and Video (FFmpeg): Multi-threaded video codec transcoding (H.264), audio codecs (MP3, OGG Opus), audio track extraction, GIF generation (Lanczos filter), and 1:1 square cropping for Telegram video messages.
  • High-Speed PDF Processing (Poppler Utils): pdftotext utilities (instant extraction of formatted text in UTF-8) and pdftoppm (page-by-page rendering of PDFs into raster images without LibreOffice overhead).
  • Optical Character Recognition (Tesseract OCR): Neural network-based extraction of printed text from scans and photos across 40+ languages.
  • Raster and Vector Graphics: Pillow libraries (including HEIC and AVIF format support), CairoSVG for vector images, and lottie for animated Telegram stickers (.TGS).
  • Books, Subtitles, and Fonts: The Calibre engine (ebook-convert), the pysubs2 subtitle parser (SRT, VTT, ASS, SSA), and the fonttools font compiler (Brotli compression in WOFF2).

4. Preventive Resource Protection (System Guard)

To protect the server from crashing due to out-of-memory errors (OOM Killer), the System Guard preventive diagnostics service is integrated. Before accepting a file for processing, the system checks key host metrics:

  • Free RAM: Minimum 500 MB of free space (guard_min_free_ram_mb).
  • Disk Space: Minimum 2 GB of free space in the /tmp directory (guard_min_free_disk_mb).
  • Task Queue: Celery queue length limit (no more than 20 pending tasks).

If limits are exceeded, the service temporarily enables protection (HTTP 503 / chat message), preventing server overload and sending an instant alert to administrators on Telegram.

5. File Lifecycle and Security (GDPR)

The architecture is designed around a Zero-Data-Footprint model:

  • User files are uploaded to a secure tmp/conversions/ volume with unique prefixes based on task IDs.
  • Files remain accessible strictly within the working session — for no more than 15 minutes (900 seconds).
  • The automatic garbage collector erases source and completed files immediately after confirming successful dispatch to the chat or upon session timeout.
  • The PostgreSQL database does not store binary files or personal document texts — tables record only anonymized technical metadata (formats, sizes in bytes, processing time, statuses).

6. Universal REST API for External Web Services

The service was initially designed as a multi-platform backend. Alongside the bot, a fully featured secure API operates for websites (e.g., built with Django) and third-party bots:

  • GET /api/v1/formats — dynamic JSON matrix of available conversion directions, synchronized with Google Sheets settings.
  • POST /api/v1/convert — universal endpoint accepting multipart/form-data (file, target format, external client ID) and returning the resulting byte stream as a direct download.
  • Bearer token authorization (WEBHOOK_REFRESH_TOKEN) with timing attack protection via secrets.compare_digest.

7. Control Panel and Observability (NiceGUI + AG Grid)

Monitoring of business metrics and system status has been moved to a native Single-Page control panel based on NiceGUI 2.x:

  • Interactive AG Grid (v32+) tables with custom Excel-style checkbox filters (aggrid_filters.js).
  • Real-time monitoring of queues, API provider latencies, and PostgreSQL / Redis ping.
  • End-to-end date filtering with seamless integration of the Metabase BI dashboard via signed JWT tokens.