All File Converter -palvelu on suunniteltu skaalautuvaksi ja hajautetuksi SaaS-järjestelmäksi nykyaikaisen Python 3.12 -asynkronisen pinon pohjalle. Arkkitehtuuri on jaettu itsenäisiin kerroksiin: verkkotapahtumien vastaanotto, tehtävien orkestrointi, raskaiden binääriprosessien eristetty suoritus ja analytiikkaputki.

1. Yleinen teknologiapino ja järjestelmäarkkitehtuuri

Alustan perustana ovat korkean suorituskyvyn (high-throughput), minimaalisen muistinkulutuksen ja vikasietoisuuden periaatteet:

  • Telegram Bot Framework: Aiogram 3.13, joka toimii Webhook-tilassa salaisten tunnisteiden validoinnilla ja viestien elinkaaren mukautetuilla suodattimilla.
  • Verkkoyhdyskäytävä ja REST API: FastAPI Uvicorn ASGI-palvelimen pohjalla, jossa on binääritiedostoiden asynkroninen suoratoisto (FileResponse) ja taustasiivous BackgroundTasks-toiminnon kautta.
  • Jononvälittäjä ja välimuisti: Redis 7 (Celery-tehtävien hallinta, kilpailutilanteiden lukkomekanismit, raa'an voiman hyökkäysten torjunta, istuntojen välimuistitallennus).
  • Taustasuorittaja (Task Queue): Celery 5.4 erillisellä työntekijöiden (worker) poolilla eristetyssä converter_worker-kontissa.
  • Tietokanta: PostgreSQL 16 ORM-kerroksella SQLAlchemy 2.0 (asyncpg), pysyvien yhteyksien poolilla (20+10 overflow) ja virheellisten tapahtumien automaattisella uudelleenyrityksellä (@db_retry).
  • Verkkoympäristö: Tunnelointi Cloudflare Zero Trust -palvelun kautta suoran IP-yhteyden estolla palvelimeen Middlewaren avulla.

2. Asynkroniset jonot ja raskaiden laskentojen eristys (Celery + Redis)

Mediatiedostojen ja toimisto-ohjelmistojen tiedostojen konvertointi aiheuttaa huippukuormitusta CPU:lle ja RAM-muistille. Jotta tulevien Telegram-viestien käsittelyprosessi ei esty raskaiden operaatioiden aikana, on otettu käyttöön tiukka eristys:

  • Tehtävien delegointi Redisiin: Muotoa valittaessa Telegram-käsittelijä rekisteröi tehtävän tietokantaan tilalla PROCESSING ja asettaa työn jonoon tasks.execute_conversion Celaryn kautta.
  • Eristetty työntekijän kontti: Konversiotyökalujen suoritus tapahtuu erillisessä Linux-kontissa, jolla on omat suoritinaika- ja muistirajoituksensa.
  • Jumittumisen hallinta ja aikakatkaisut: Ulkoisten työkalujen kutsut on kiedottu asynkroniseen kontekstiin tiukalla aikarajoituksella (conversion_timeout_sec = 180). Rajan ylittyessä prosessi lopetetaan pakotetusti komennolla proc.kill(), mikä vapauttaa resurssit.
  • Vikasietoinen Fallback: Redis-välittäjän ollessa tilapäisesti tavoittamattomissa paikallinen asynkroninen välittäjä nappaa tehtävän automaattisesti ja suorittaa sen suoraan ilman, että käyttäjälle aiheutuu virhettä.

3. Erikoistuneiden konversio-ohjelmistojen putki

Jokaiselle tietotyypille käytetään erikoistuneita natiivityökaluja ja kirjastoja:

  • Asiakirjat ja taulukot (LibreOffice): Päättönä toimiva toimistopaketti (soffice --headless) DOCX-, XLSX-, PPTX-, RTF-, ODT-tiedostojen tarkkaan renderöintiin PDF-muotoon tai tekstitiedostoiksi.
  • Suoratoistoääni ja -video (FFmpeg): Videokoodekkien (H.264), äänikoodekkien (MP3, OGG Opus) monisäikeinen uudelleenkoodaus, ääniraitojen poiminta, GIF-tiedostojen luonti (Lanczos-suodatin) ja Telegram-videoviestien neliömäinen rajaus (1:1).
  • Suurnopeuksinen PDF-käsittely (Poppler Utils): Työkalut pdftotext (muotoillun tekstin välitön poiminta UTF-8-muodossa) ja pdftoppm (PDF-tiedostojen sivukohtainen renderöinti bittikartoiksi ilman LibreOfficen lisäkuormitusta).
  • Optinen tekstintunnistus (Tesseract OCR): Neuroverkkopohjainen painetun tekstin poiminta skannauksista ja valokuvista yli 40 kielellä.
  • Bitti- ja vektorilogiikka: Kirjastot Pillow (mukaan lukien HEIC- ja AVIF-muotojen tuki), CairoSVG vektorikuville ja lottie Telegramin animoiduille tarratiedostoille (.TGS).
  • Kirjat, tekstitykset ja fontit: Moottori Calibre (ebook-convert), tekstitysten jäsennin pysubs2 (SRT, VTT, ASS, SSA) ja fonttikääntäjä fonttools (Brotli-pakkaus WOFF2-muotoon).

4. Resurssien ennaltaehkäisevä suojaus (System Guard)

Palvelimen kaatumisen estämiseksi muistin loppumisen (OOM Killer) vuoksi on otettu käyttöön ennaltaehkäisevän diagnostiikan palvelu System Guard. Ennen tiedoston vastaanottamista käsittelyyn järjestelmä tarkistaa keskeiset isäntäkoneen metriikat:

  • Vapaa keskusmuisti (RAM): Vähintään 500 Mt vapaata kapasiteettia (guard_min_free_ram_mb).
  • Levytila: Vähintään 2 Gt vapaata tilaa hakemistossa /tmp (guard_min_free_disk_mb).
  • Tehtäväjono: Celery-jonon pituuden rajoitus (enintään 20 odottavaa tehtävää).

Rajojen ylittyessä palvelu kytkee suojauksen väliaikaisesti päälle (HTTP 503 / viesti chatissa), estäen palvelimen ylikuormittumisen ja lähettäen välittömän hälytyksen ylläpitäjille Telegramiin.

5. Tiedostojen elinkaari ja turvallisuus (GDPR)

Arkkitehtuuri on suunniteltu Zero-Data-Footprint-mallin mukaisesti:

  • Käyttäjien tiedostot ladataan suojatulle tmp/conversions/-taltiolle tehtävän tunnisteisiin perustuvilla yksilöllisillä etuliitteillä.
  • Tiedostot pysyvät saatavilla tiukasti työsistunnon ajan – enintään 15 minuuttia (900 sekuntia).
  • Automaattinen roskienkerääjä poistaa alkuperäiset ja valmiit tiedostot heti sen jälkeen, kun on varmistettu onnistunut lähetys chattiin tai kun istunnon aikakatkaisu on umpeutunut.
  • PostgreSQL-tietokanta ei säilytä binääritiedostoja tai asiakirjojen henkilökohtaisia tekstejä – taulukoihin tallennetaan vain anonymisoituja teknisiä metatietoja (muodot, koot tavuina, ajoaika, tilat).

6. Universaali REST API ulkoisille verkkopalveluille

Palvelu on alun perin suunniteltu monialustaiseksi taustajärjestelmäksi. Botin ohella toimii täysipainoinen ja suojattu ohjelmistorajapinta verkkosivustoille (esimerkiksi Djangolla toteutetuille) ja kolmansien osapuolten boteille:

  • GET /api/v1/formats — dynaaminen JSON-matriisi saatavilla olevista konversiosuunnista, synkronoituna Google Taulukoiden asetusten kanssa.
  • POST /api/v1/convert — universaali rajapintapiste, joka vastaanottaa multipart/form-data -aineiston (tiedosto, kohdemuoto, ulkoisen asiakkaan ID) ja palauttaa valmiin tavuvirran suorana latauksena.
  • Todennus Bearer-tunnisteilla (WEBHOOK_REFRESH_TOKEN) suojauksella ajoitushyökkäyksiä vastaan secrets.compare_digest -menetelmällä.

7. Hallintapaneeli ja Observability (NiceGUI + AG Grid)

Liiketoimintamittareiden ja järjestelmän tilan valvonta on tuotu natiiviin Single-Page-hallintapaneeliin, joka perustuu NiceGUI 2.x -kirjastoon:

  • Interaktiiviset AG Grid (v32+) -taulukot mukautetuilla Excel-tyylisillä valintaruutusuodattimilla (aggrid_filters.js).
  • Jonojen, API-palveluntarjoajien viiveiden sekä PostgreSQL / Redis -pingauksen reaaliaikainen valvonta.
  • Kattava päivämääräsuodatus Metabase BI-koontinäytön saumattomalla integraatiolla allekirjoitettujen JWT-tunnisteiden kautta.