O serviço All File Converter foi projetado como um sistema SaaS distribuído e escalável baseado em uma stack assíncrona moderna em Python 3.12. A arquitetura é dividida em camadas independentes: recepção de eventos de rede, orquestração de tarefas, execução isolada de processos binários pesados e o fluxo analítico.

1. Stack tecnológica geral e arquitetura do sistema

A plataforma é fundamentada nos princípios de alta taxa de transferência (high-throughput), consumo mínimo de memória e proteção contra falhas:

  • Telegram Bot Framework: Aiogram 3.13, operando no modo Webhook com validação de tokens secretos e filtros personalizados de ciclo de vida de mensagens.
  • Gateway web e REST API: FastAPI baseado no servidor ASGI Uvicorn com entrega assíncrona em fluxo de arquivos binários (FileResponse) e limpeza em segundo plano via BackgroundTasks.
  • Broker de filas e cache: Redis 7 (gerenciamento de tarefas do Celery, bloqueios contra condições de corrida, proteção contra força bruta, cache de sessões).
  • Executor em segundo plano (Task Queue): Celery 5.4 com um pool dedicado de workers em um container isolado converter_worker.
  • Banco de dados: PostgreSQL 16 com a camada ORM SQLAlchemy 2.0 (asyncpg), pool de conexões persistentes (20+10 overflow) e nova tentativa automática para transações com falha (@db_retry).
  • Contorno de rede: Tunelamento via Cloudflare Zero Trust com bloqueio de acesso direto por IP ao servidor através de Middleware.

2. Filas assíncronas e isolamento de computação pesada (Celery + Redis)

A conversão de arquivos de mídia e pacotes de escritório gera picos de carga de CPU e RAM. Para garantir que o processo de tratamento de mensagens recebidas no Telegram não seja bloqueado durante operações pesadas, foi implementado um isolamento rigoroso:

  • Delegação de tarefas para o Redis: Ao selecionar um formato, o manipulador do Telegram registra a tarefa no banco de dados com o status PROCESSING e coloca a tarefa na fila tasks.execute_conversion via Celery.
  • Container isolado do worker: A execução dos utilitários de conversão ocorre em um container Linux separado com seu próprio limite de tempo de processador e memória.
  • Controle de travamentos e timeouts: As chamadas a utilitários externos são envolvidas em um contexto assíncrono com controle rígido de tempo (conversion_timeout_sec = 180). Se o limite for excedido, o processo é encerrado à força via proc.kill(), liberando recursos.
  • Fallback tolerante a falhas: Em caso de indisponibilidade temporária do broker Redis, a tarefa é interceptada automaticamente pelo despachante assíncrono local e executada diretamente sem falhas para o usuário.

3. Pipeline de engines especializados de conversão

Para cada tipo de dados, são utilizados utilitários e bibliotecas nativos altamente especializados:

  • Documentos e planilhas (LibreOffice): Pacote de escritório headless (soffice --headless) para renderização precisa de DOCX, XLSX, PPTX, RTF, ODT em formato PDF ou arquivos de texto.
  • Áudio e vídeo em streaming (FFmpeg): Transcodificação multithread de codecs de vídeo (H.264), codecs de áudio (MP3, OGG Opus), extração de trilhas sonoras, geração de GIF (filtro Lanczos) e corte quadrado (1:1) de mensagens de vídeo do Telegram.
  • Processamento de PDF de alta velocidade (Poppler Utils): Utilitários pdftotext (extração instantânea de texto formatado em UTF-8) e pdftoppm (renderização página por página de PDF em imagens raster sem os overheads do LibreOffice).
  • Reconhecimento Óptico de Caracteres (Tesseract OCR): Extração de texto impresso baseada em redes neurais a partir de digitalizações e fotos em mais de 40 idiomas.
  • Gráficos raster e vetoriais: Bibliotecas Pillow (incluindo suporte aos formatos HEIC e AVIF), CairoSVG para imagens vetoriais e lottie para adesivos animados do Telegram (.TGS).
  • Livros, legendas e fontes: Engine Calibre (ebook-convert), parser de legendas pysubs2 (SRT, VTT, ASS, SSA) e compilador de fontes fonttools (compressão Brotli em WOFF2).

4. Proteção preventiva de recursos (System Guard)

Para proteger contra quedas do servidor devido à escassez de memória (OOM Killer), foi implementado o serviço de diagnóstico preventivo System Guard. Antes de aceitar um arquivo para processamento, o sistema verifica as principais métricas do host:

  • Memória RAM livre: Mínimo de 500 MB de volume livre (guard_min_free_ram_mb).
  • Espaço em disco: Mínimo de 2 GB de espaço livre no diretório /tmp (guard_min_free_disk_mb).
  • Fila de tarefas: Limitação do tamanho da fila do Celery (não mais que 20 tarefas pendentes).

Se os limites forem excedidos, o serviço ativa temporariamente a proteção (HTTP 503 / mensagem no chat), evitando a sobrecarga do servidor e enviando um alerta instantâneo aos administradores no Telegram.

5. Ciclo de vida dos arquivos e segurança (GDPR)

A arquitetura foi projetada seguindo o modelo Zero-Data-Footprint:

  • Os arquivos dos usuários são carregados no volume protegido tmp/conversions/ com prefixos exclusivos baseados em identificadores de tarefas.
  • Os arquivos permanecem acessíveis estritamente dentro da sessão de trabalho — por no máximo 15 minutos (900 segundos).
  • O coletor de lixo automático apaga os arquivos originais e prontos imediatamente após a confirmação do envio bem-sucedido para o chat ou após o término do tempo limite da sessão.
  • O banco de dados PostgreSQL não armazena arquivos binários ou textos pessoais de documentos — nas tabelas são registrados apenas metadados técnicos anonimizados (formatos, tamanhos em bytes, tempo de execução, status).

6. REST API universal para serviços web externos

O serviço foi inicialmente projetado como um backend multiplataforma. Juntamente com o bot, opera uma interface de programação protegida completa para sites (por exemplo, em Django) e bots de terceiros:

  • GET /api/v1/formats — matriz JSON dinâmica de direções de conversão disponíveis, sincronizada com as configurações do Google Sheets.
  • POST /api/v1/convert — endpoint universal que aceita multipart/form-data (arquivo, formato de destino, ID do cliente externo) e retorna o fluxo de bytes pronto na forma de download direto.
  • Autorização por Bearer tokens (WEBHOOK_REFRESH_TOKEN) com proteção contra ataques de tempo via secrets.compare_digest.

7. Painel de controle e Observability (NiceGUI + AG Grid)

O monitoramento de indicadores de negócios e do estado do sistema foi transferido para um painel de controle Single-Page nativo baseado em NiceGUI 2.x:

  • Tabelas interativas AG Grid (v32+) com filtros de caixa de seleção personalizados estilo Excel (aggrid_filters.js).
  • Monitoramento em tempo real de filas, atrasos de provedores de API e ping do PostgreSQL / Redis.
  • Filtragem abrangente por datas com integração perfeita do dashboard de BI Metabase através de tokens JWT assinados.