Der Service All File Converter ist als skalierbares, verteiltes SaaS-System auf Basis des modernen asynchronen Python 3.12 Stacks konzipiert. Die Architektur ist in unabhängige Schichten unterteilt: Netzwerk-Event-Empfang, Task-Orchestrierung, isolierte Ausführung schwerer Binärprozesse und die Analyseschleife.

1. Gesamter Tech-Stack und Systemarchitektur

Die Plattform basiert auf Prinzipien von hoher Leistung (High-Throughput), minimalem Speicherbedarf und Ausfallsicherheit:

  • Telegram Bot Framework: Aiogram 3.13, das im Webhook-Modus mit Signet-Token-Validierung und benutzerdefinierten Filtern für den Nachrichtenzahl-Lebenszyklus arbeitet.
  • Web-Gateway und REST API: FastAPI auf Basis des Uvicorn ASGI-Servers mit asynchronem Binärdatei-Streaming (FileResponse) und Hintergrundbereinigung über BackgroundTasks.
  • Queue-Broker und Cache: Redis 7 (Celery-Task-Verwaltung, Race-Condition-Sperren, Brute-Force-Schutz, Sitzungs-Caching).
  • Hintergrund-Executor (Task Queue): Celery 5.4 mit einem dedizierten Worker-Pool in einem isolierten converter_worker-Container.
  • Datenbank: PostgreSQL 16 mit der SQLAlchemy 2.0 (asyncpg) ORM-Schicht, einem dauerhaften Verbindungspool (20+10 overflow) und automatischen Wiederholungsversuchen für fehlerhafte Transaktionen (@db_retry).
  • Netzwerk-Peripherie: Tunneling über Cloudflare Zero Trust mit Blockierung des direkten IP-Zugriffs auf den Server mittels Middleware.

2. Asynchrone Warteschlangen und Isolierung schwerer Berechnungen (Celery + Redis)

Die Konvertierung von Mediendateien und Office-Paketen erzeugt Spitzenlasten bei CPU und RAM. Um zu verhindern, dass die Verarbeitung eingehender Telegram-Nachrichten bei schweren Operationen blockiert wird, ist eine strikte Isolierung implementiert:

  • Aufgabendelegierung an Redis: Bei der Auswahl des Formats registriert der Telegram-Handler die Aufgabe mit dem Status PROCESSING in der Datenbank und stellt den Job über Celery in die Warteschlange tasks.execute_conversion.
  • Isolierter Worker-Container: Die Ausführung von Konvertierungsprogrammen erfolgt in einem separaten Linux-Container mit eigenen Rechenzeit- und Speicherlimits.
  • Hänger-Kontrolle und Timeouts: Aufrufe externer Tools sind in einen asynchronen Kontext mit strenger Zeitüberwachung eingebettet (conversion_timeout_sec = 180). Bei Überschreitung des Limits wird der Prozess gewaltsam über proc.kill() beendet, um Ressourcen freizugeben.
  • Ausfallsicherer Fallback: Bei vorübergehender Nichtverfügbarkeit des Redis-Brokers wird die Aufgabe automatisch vom lokalen asynchronen Dispatcher abgefangen und direkt ausgeführt, ohne dass es zu einem Fehler für den Benutzer kommt.

3. Pipeline spezialisierter Konvertierungs-Engines

Für jeden Datentyp werden hochspezialisierte native Tools und Bibliotheken eingesetzt:

  • Dokumente und Tabellen (LibreOffice): Ein Headless Office-Paket (soffice --headless) für präzises Rendern von DOCX, XLSX, PPTX, RTF, ODT in PDF oder Textdateien.
  • Streaming-Audio und -Video (FFmpeg): Multithread-Transkodierung von Videocodecs (H.264), Audiocodecs (MP3, OGG Opus), Extrahieren von Audiospuren, Generieren von GIFs (Lanczos-Filter) und quadratisches Zuschneiden (1:1) von Telegram-Videobotschaften.
  • Hochgeschwindigkeits-PDF-Verarbeitung (Poppler Utils): Die Tools pdftotext (sofortiges Extrahieren von formatiertem Text in UTF-8) und pdftoppm (seitenweises Rendern von PDFs in Rasterbilder ohne LibreOffice-Overhead).
  • Optische Zeichenerkennung (Tesseract OCR): Neuronale Netzwerk-Extraktion von gedrucktem Text aus Scans und Fotos in über 40 Sprachen.
  • Raster- und Vektorgrafiken: Die Bibliotheken Pillow (einschließlich Unterstützung für HEIC- und AVIF-Formate), CairoSVG für Vektorgrafiken und lottie für animierte Telegram-Sticker (.TGS).
  • Bücher, Untertitel und Schriften: Die Calibre-Engine (ebook-convert), der Untertitel-Parser pysubs2 (SRT, VTT, ASS, SSA) und der Font-Compiler fonttools (Brotli-Kompression in WOFF2).

4. Präventiver Ressourcenschutz (System Guard)

Um Serverabstürze aufgrund von Speichermangel (OOM Killer) zu verhindern, wurde der präventive Diagnosedienst System Guard implementiert. Vor der Annahme einer Datei zur Verarbeitung überprüft das System wichtige Host-Metriken:

  • Freier Arbeitsspeicher (RAM): Mindestens 500 MB freier Speicher (guard_min_free_ram_mb).
  • Festplattenspeicher: Mindestens 2 GB freier Speicherplatz im Verzeichnis /tmp (guard_min_free_disk_mb).
  • Warteschlange: Begrenzung der Celery-Warteschlangenlänge (höchstens 20 wartende Aufgaben).

Wenn die Grenzwerte überschritten werden, aktiviert der Dienst vorübergehend den Schutz (HTTP 503 / Nachricht im Chat), verhindert so eine Überlastung des Servers und sendet sofort einen Alarm an die Administratoren in Telegram.

5. Dateilebenszyklus und Sicherheit (GDPR)

Die Architektur ist nach dem Zero-Data-Footprint-Modell konzipiert:

  • Benutzerdateien werden mit eindeutigen Präfixen basierend auf den Task-IDs in ein geschütztes tmp/conversions/-Volume hochgeladen.
  • Dateien bleiben ausschließlich im Rahmen der Arbeitssitzung zugänglich — nicht länger als 15 Minuten (900 Sekunden).
  • Der automatische Garbage Collector löscht Quell- und Zieldateien sofort nach Bestätigung des erfolgreichen Versands in den Chat oder nach Ablauf des Sitzungs-Timeouts.
  • Die PostgreSQL-Datenbank speichert keine Binärdateien oder persönlichen Dokumententexte — in den Tabellen werden nur anonymisierte technische Metadaten erfasst (Formate, Größen in Bytes, Laufzeit, Status).

6. Universelle REST API für externe Webdienste

Der Service ist von Anfang an als plattformübergreifendes Backend konzipiert. Neben dem Bot funktioniert eine vollwertige, geschützte programmierbare Schnittstelle für Webseiten (z. B. auf Basis von Django) und Bots von Drittanbietern:

  • GET /api/v1/formats — eine dynamische JSON-Matrix der verfügbaren Konvertierungsrichtungen, synchronisiert mit den Google Sheets-Einstellungen.
  • POST /api/v1/convert — ein universeller Endpunkt, der multipart/form-data akzeptiert (Datei, Zielformat, externer Client-ID) und den fertigen Bytestream als direkten Download ausgibt.
  • Authentifizierung über Bearer-Token (WEBHOOK_REFRESH_TOKEN) mit Schutz vor Timing-Angriffen über secrets.compare_digest.

7. Bedienfeld und Observability (NiceGUI + AG Grid)

Die Überwachung von Geschäftskennzahlen und Systemstatus wurde in ein natives Single-Page-Bedienfeld auf Basis von NiceGUI 2.x ausgelagert:

  • Interaktive Tabellen AG Grid (v32+) mit benutzerdefinierten Excel-ähnlichen Checkbox-Filtern (aggrid_filters.js).
  • Echtzeit-Überwachung von Warteschlangen, Verzögerungen der API-Anbieter und des Pings von PostgreSQL / Redis.
  • Durchgängige Filterung nach Datum mit nahtloser Integration des Metabase BI-Dashboards über signierte JWT-Token.