De All File Converter-service is ontworpen als een schaalbaar, gedistribueerd SaaS-systeem op basis van een moderne asynchrone Python 3.12-stack. De architectuur is verdeeld in onafhankelijke lagen: netwerkevenementontvangst, taakorkestratie, gesoleerde uitvoering van zware binaire processen en de analytische lus.

1. Algemene technologiestack en systeemarchitectuur

Het platform is gebaseerd op principes van hoge doorvoer (high-throughput), minimaal geheugengebruik en storingsbeveiliging:

  • Telegram Bot Framework: Aiogram 3.13, werkend in Webhook-modus met validatie van geheime tokens en aangepaste filters voor de levenscyclus van berichten.
  • Webgateway en REST API: FastAPI op basis van een ASGI-server Uvicorn met asynchrone streaming van binaire bestanden (FileResponse) en achtergrondopschoning via BackgroundTasks.
  • Wachtrijbroker en cache: Redis 7 (beheer van Celery-taken, race-condition-vergrendelingen, beveiliging tegen brute force, sessiecaching).
  • Achtergronduitvoerder (Task Queue): Celery 5.4 met een toegewezen pool van workers in een geisoheerde converter_worker-container.
  • Database: PostgreSQL 16 met een ORM-laag SQLAlchemy 2.0 (asyncpg), een pool van permanente verbindingen (20+10 overflow) en automatische herhaling van mislukte transacties (@db_retry).
  • Netwerklust: Tunneling via Cloudflare Zero Trust met blokkering van directe IP-toegang tot de server via Middleware.

2. Asynchrone wachtrijen en isolatie van zware berekeningen (Celery + Redis)

De conversie van mediabestanden en kantoorpakketten zorgt voor piekbelastingen op de CPU en RAM. Om te voorkomen dat het verwerken van inkomende berichten in Telegram wordt geblokkeerd tijdens zware operaties, is strikte isolatie geïmplementeerd:

  • Delegeren van taken aan Redis: Bij het selecteren van het formaat registreert de Telegram-handler de taak in de database met de status PROCESSING en plaatst de taak in de wachtrij tasks.execute_conversion via Celery.
  • Geïsoleerde worker-container: De uitvoering van conversiehulpprogramma's vindt plaats in een afzonderlijke Linux-container met een eigen limiet voor procestijd en geheugen.
  • Besturing van vastlopen en timeouts: Aanroepen van externe hulpprogramma's zijn verpakt in een asynchrone context met strikte tijdslimieten (conversion_timeout_sec = 180). Bij overschrijding van de limiet wordt het proces geforceerd beëindigd via proc.kill(), waardoor resources vrijkomen.
  • Fouttolerante Fallback: Bij tijdelijke onbeschikbaarheid van de Redis-broker wordt de taak automatisch overgenomen door de lokale asynchrone dispatcher en direct uitgevoerd zonder storing voor de gebruiker.

3. Pijplijn van gespecialiseerde conversie-engines

Voor elk datattype worden gespecialiseerde native hulpprogramma's en bibliotheken gebruikt:

  • Documenten en tabellen (LibreOffice): Een headless kantoorpakket (soffice --headless) voor nauwkeurige rendering van DOCX, XLSX, PPTX, RTF, ODT naar PDF-formaat of tekstbestanden.
  • Streaming audio en video (FFmpeg): Multithreaded transcoding van videocodecs (H.264), audiocodecs (MP3, OGG Opus), extractie van geluidstracks, generatie van GIF (Lanczos-filter) en vierkante bijsnijding (1:1) van Telegram-videoberichten.
  • Hogesnelheids-PDF-verwerking (Poppler Utils): Hulpprogramma's pdftotext (onmiddellijke extractie van geformatteerde tekst in UTF-8) en pdftoppm (paginagewijze rendering van PDF naar rasterafbeeldingen zonder de overhead van LibreOffice).
  • Optische tekenherkenning (Tesseract OCR): Neuraal netwerk voor het extraheren van gedrukte tekst van scans en foto's in meer dan 40 talen.
  • Raster- en vectorgrafie: Bibliotheken Pillow (inclusief ondersteuning voor HEIC- en AVIF-formaten), CairoSVG voor vectorafbeeldingen en lottie voor geanimeerde Telegram-stickers (.TGS).
  • Boeken, ondertitels en lettertypen: Engine Calibre (ebook-convert), ondertitelparser pysubs2 (SRT, VTT, ASS, SSA) en lettertypecompiler fonttools (Brotli-compressie in WOFF2).

4. Preventieve resourcebeveiliging (System Guard)

Om te voorkomen dat de server crasht door een gebrek aan geheugen (OOM Killer) is de preventieve diagnosetervice System Guard geïmplementeerd. Voordat een bestand in behandeling wordt genomen, controleert het systeem de belangrijkste metrische gegevens van de host:

  • Vrij werkgeheugen (RAM): Minimaal 500 MB vrije capaciteit (guard_min_free_ram_mb).
  • Schijfruimte: Minimaal 2 GB vrije ruimte in de directory /tmp (guard_min_free_disk_mb).
  • Taakwachtrij: Beperking van de lengte van de Celery-wachtrij (niet meer dan 20 wachtende taken).

Bij overschrijding van de limieten schakelt de service tijdelijk beveiliging in (HTTP 503 / bericht in de chat), wat overbelasting van de server voorkomt en direct een waarschuwing naar beheerders stuurt in Telegram.

5. Levenscyclus van bestanden en beveiliging (GDPR)

De architectuur is ontworpen volgens het Zero-Data-Footprint-model:

  • Gebruikersbestanden worden geüpload naar een beveiligde volume tmp/conversions/ met unieke voorvoegsels op basis van taak-ID's.
  • Bestanden blijven strikt toegankelijk binnen de werksessie — niet langer dan 15 minuten (900 seconden).
  • De automatische garbagecollector wist de originele en gereedgemaakte bestanden onmiddellijk na bevestiging van succesvolle verzending naar de chat of na afloop van de sessietime-out.
  • De PostgreSQL-database slaat geen binaire bestanden of persoonlijke documentteksten op — in de tabellen worden alleen geanonimiseerde technische metagegevens vastgelegd (formaten, groottes in bytes, verwerkingstijd, statussen).

6. Universele REST API voor externe webservices

De service is vanaf het begin ontworpen als een multiplatform-backend. Naast de bot is er een volledig beveiligde programmatische interface actief voor websites (bijvoorbeeld op basis van Django) en externe bots:

  • GET /api/v1/formats — een dynamische JSON-matrix van beschikbare conversierichtingen, gesynchroniseerd met de instellingen van Google Spreadsheets.
  • POST /api/v1/convert — een universeel eindpunt dat multipart/form-data accepteert (bestand, doelformaat, ID van externe klant) en een gereed byte-stream retourneert als directe download.
  • Autorisatie via Bearer-tokens (WEBHOOK_REFRESH_TOKEN) met beveiliging tegen timingaanvallen via secrets.compare_digest.

7. Beheerpaneel en Observability (NiceGUI + AG Grid)

Monitoring van bedrijfsindicatoren en de systeemstatus is ondergebracht in een native Single-Page beheerpaneel op basis van NiceGUI 2.x:

  • Interactieve tabellen AG Grid (v32+) met aangepaste Excel-stijl checkbox-filters (aggrid_filters.js).
  • Realtime monitoring van wachtrijen, vertragingen van API-providers en pings van PostgreSQL / Redis.
  • Doorlopende filtering op datums met naadloze integratie van het BI-dashboard Metabase via ondertekende JWT-tokens.