All File Converterサービスは、最新の非同期Python 3.12スタックをベースにした、スケーラブルな分散型SaaSシステムとして設計されています。アーキテクチャは、ネットワークイベントの受信、タスクのオーケストレーション、重いバイナリプロセスの分離実行、分析ループという独立した層に分割されています。

1. 全体的なテクノロジースタックとシステムアーキテクチャ

プラットフォームの基盤には、高スループット（high-throughput）、最小限のメモリ消費、および障害からの保護という原則が組み込まれています：

  • Telegram Bot Framework: Aiogram 3.13。シークレットトークンの検証とカスタムメッセージライフサイクルフィルターを備えたWebhookモードで動作します。
  • WebゲートウェイとREST API: ASGIサーバーUvicornをベースにしたFastAPI。バイナリファイルの非同期ストリーミング配信（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を通じたトンネリング。Middlewareによりサーバーへの直接IPアクセスをブロックします。

2. 非同期キューと重い計算の分離（Celery + Redis）

メディアファイルやオフィススイートの変換は、CPUとRAMにピーク負荷をかけます。Telegram内の受信メッセージの処理プロセスが重い操作によってブロックされないよう、厳格な分離が実装されています：

  • Redisへのタスクの委任: フォーマットが選択されると、TelegramハンドラーはステータスをPROCESSINGとしてDBにタスクを登録し、Celeryを介してtasks.execute_conversionキューにジョブを配置します。
  • 分離されたワーカーコンテナ: 変換ユーティリティの実行は、独自のCPU時間とメモリの制限を持つ独立したLinuxコンテナ内で行われます。
  • フリーズの制御とタイムアウト: 外部ユーティリティの呼び出しは、厳格な時間制御（conversion_timeout_sec = 180）を備えた非同期コンテキストでラップされています。制限時間を超えると、プロセスはproc.kill()によって強制終了され、リソースが解放されます。
  • 耐障害性フォールバック: Redisブローカーが一時的に利用できない場合、タスクはローカルの非同期ディスパッチによって自動的にインターセプトされ、ユーザーに障害を与えることなく直接実行されます。

3. 特殊な変換エンジンのパイプライン

データ型ごとに、特化型のネイティブユーティリティとライブラリが使用されます：

  • ドキュメントと表計算（LibreOffice）: DOCX、XLSX、PPTX、RTF、ODTをPDFまたはテキストファイルに正確にレンダリングするためのヘッドレスオフィススイート（soffice --headless）。
  • ストリーミング音声と動画（FFmpeg）: ビデオコーデック（H.264）、オーディオコーデック（MP3、OGG Opus）のマルチスレッド再エンコーディング、音声トラックの抽出、GIF生成（Lanczosフィルター）、およびTelegramビデオメッセージの正方形トリミング（1:1）。
  • 高速PDF処理（Poppler Utils）: pdftotext（UTF-8形式のテキストの即時抽出）およびpdftoppm（LibreOfficeのオーバーヘッドなしでPDFをラスター画像にページ単位でレンダリング）ユーティリティ。
  • 光学的文字認識（Tesseract OCR）: 40以上の言語でのスキャンや写真からのニューラルネットワークによる印刷テキストの抽出。
  • ラスターおよびベクターグラフィックス: Pillowライブラリ（HEICおよびAVIFフォーマットのサポートを含む）、ベクター画像用のCairoSVG、Telegramアニメーションスタンプ（.TGS）用のlottie。
  • 書籍、字幕、フォント: Calibreエンジン（ebook-convert）、字幕パーサーpysubs2（SRT、VTT、ASS、SSA）、フォントコンパイラfonttools（WOFF2へのBrotli圧縮）。

4. 予防的リソース保護（System Guard）

メモリ不足（OOM Killer）によるサーバーのダウンを防ぐため、予防的診断サービスSystem Guardが導入されています。ファイルを処理のために受け入れる前に、システムはホストの主要なメトリクスを確認します：

  • 空き物理メモリ（RAM）: 最低500MBの空き容量（guard_min_free_ram_mb）。
  • ディスク容量: /tmpディレクトリに最低2GBの空き容量（guard_min_free_disk_mb）。
  • タスクキュー: Celeryキューの長さの制限（保留中のタスクが20個を超えないこと）。

制限値を超えた場合、サービスは一時的に保護機能を有効にし（HTTP 503 / チャットでのメッセージ送信）、サーバーの過負荷を防ぎ、Telegramで管理者に即座にアラートを送信します。

5. ファイルのライフサイクルとセキュリティ（GDPR）

アーキテクチャはZero-Data-Footprintモデルに基づいて設計されています：

  • ユーザーのファイルは、タスクIDをベースにした一意のプレフィックスが付いた安全なボリュームtmp/conversions/にアップロードされます。
  • ファイルはワーキングセッションの範囲内でのみ厳密にアクセス可能であり、15分以内（900秒）保持されます。
  • 自動ガベージコレクション機能により、チャットへの正常な送信の確認直後、またはセッションタイムアウトの経過時に、元のファイルと完成したファイルが即座に消去されます。
  • PostgreSQLデータベースはバイナリファイルやドキュメントの個人用テキストを保存しません。テーブルに記録されるのは、匿名化された技術的メタデータ（フォーマット、バイト単位のサイズ、実行時間、ステータス）のみです。

6. 外部Webサービス向けの汎用REST API

本サービスは、最初からマルチプラットフォームのバックエンドとして設計されています。ボットと並行して、ウェブサイト（Djangoなど）やサードパーティのボット向けの完全な保護されたプログラムインターフェイスが機能しています：

  • GET /api/v1/formats — Googleスプレッドシートの設定と同期された、利用可能な変換方向の動的なJSONマトリックス。
  • POST /api/v1/convert — multipart/form-data（ファイル、ターゲットフォーマット、外部クライアントID）を受け入れ、直接ダウンロードの形でバイトストリームを出力する汎用エンドポイント。
  • secrets.compare_digestを通じたタイミング攻撃からの保護を備えた、Bearerトークン（WEBHOOK_REFRESH_TOKEN）による認証。

7. コントロールパネルとObservability（NiceGUI + AG Grid）

ビジネス指標とシステムの稼働状態のモニタリングは、NiceGUI 2.xをベースにしたネイティブのSingle-Pageコントロールパネルに出力されます：

  • カスタムのExcelスタイルチェックボックスフィルター（aggrid_filters.js）を備えたインタラクティブなAG Grid (v32+)テーブル。
  • キュー、APIプロバイダーの遅延、およびPostgreSQL / Redisのプングのリアルタイムモニタリング。
  • 署名付きJWTトークンを介したMetabase BIダッシュボードのシームレスな統合による、日付によるエンドツーエンドのフィルタリング。