Fatos Eleitorais

Visão Geral

Fatos Eleitorais é uma plataforma de transparência política que pega entrevistas e debates longos e transforma em declarações pesquisáveis, com minutagem exata e trilha completa até o vídeo original. A ideia é reduzir o atrito para verificar “o que esse candidato realmente falou?”, respondendo com link direto para o trecho exato do vídeo, data, contexto e categorização por tema.

O fluxo começa no vídeo bruto (YouTube, por exemplo), passa por transcrição automática e, a partir daí, um pipeline de IA segmenta o conteúdo em perguntas e respostas, extrai as declarações relevantes e organiza tudo por candidato, tema e tipo de fala (promessa, avaliação de governo, proposta etc.). Cada segmento ainda passa por revisão humana antes de ser publicado, garantindo que erros de IA não virem “verdade oficial”.

Meu papel foi de projeto solo: desenhei a arquitetura, implementei o frontend em Next.js, a API em Fastify com TypeScript, o worker de IA em Python, a fila de jobs em PostgreSQL, além da esteira de deploy e a infraestrutura em produção. A primeira versão beta está no ar com processamento de entrevistas, busca por falas e um painel de curadoria.

Embora esteja em pré-lançamento, a plataforma já roda com uma arquitetura preparada para eleições nacionais: múltiplos workers concorrentes, jobs encadeados, reprocessamento resiliente a falhas e um modelo de dados que suporta eleições, cargos, candidaturas e histórico cronológico de discurso.

Diferencial Principal

O diferencial não é “mais um buscador de vídeos”, mas a combinação de três elementos:

1. Segmentação semântica em cima de entrevistas longas, tratando a unidade básica como “pergunta + resposta”, não como cortes arbitrários de tempo.
2. Pipeline de IA orquestrado para extrair não só falas, mas também promessas eleitorais, com rastro até o segundo exato do vídeo original.
3. Curadoria humana embutida no fluxo como etapa obrigatória, não opcional, garantindo que o resultado final seja auditável e confiável.

Tecnicamente, o projeto se diferencia por resolver problemas que normalmente seriam atacados com várias peças adicionais (message broker, serviço de embeddings dedicado, sistema de notificação separado) usando uma arquitetura enxuta: PostgreSQL como fila de jobs e backbone de eventos, workers em Python consumindo jobs, e um frontend protegido via CSP que fala com a API exclusivamente através de Server Actions do Next.js.

O pipeline de segmentação usa uma LLM com reasoning para respeitar a narrativa do debate em vez de depender apenas de quebras de linha ou marcadores de speaker na legenda, o que permite lidar bem com transcrições imperfeitas e conversas que cruzam limites de chunk.

Arquitetura

• Frontend (Next.js 16 / React 19): SPA/SSR que exibe a busca de declarações, páginas de candidatos, linha do tempo de falas e painel de revisão; todas as mutações passam por Server Actions, que chamam a API via REST no servidor.
• API Gateway (Fastify 5 + TypeScript): Expõe endpoints REST internos para ingestão de vídeos, gerenciamento de jobs, consulta de declarações, promessas, temas e estrutura eleitoral; valida payloads com Zod e acessa o banco via Drizzle ORM.
• Banco de Dados (PostgreSQL): Armazena toda a modelagem de eleições (candidatos, cargos, ciclos eleitorais), vídeos, transcrições, segmentos, declarações, promessas, alertas de usuários, além de atuar como fila de jobs e canal de notificação.
• Worker de IA (Python 3.12 + LangChain/LangGraph): Consome jobs da fila (segmentação, extração de falas, extração de promessas), chama LLM para análise de texto e gera segmentos enriquecidos com metadados; grava resultados diretamente no PostgreSQL.
• Serviço de Embeddings: Converte trechos de fala em vetores para detecção de duplicatas e preparação de busca semântica futura; hoje usado principalmente para merge e deduplicação de segmentos.
• Storage de Arquivos: Guarda SRTs, transcrições e artefatos intermediários de processamento, desacoplados do banco relacional.
• Sistema de E-mail: Envia notificações de novos conteúdos para usuários que seguem candidatos ou temas específicos.
• Infraestrutura e Deploy (Docker + GitHub Actions + Cloudflare): Cada serviço (API, frontend, worker) possui seu Dockerfile; pipelines no GitHub Actions fazem build, testes, migrações de banco e deploy; Cloudflare faz proxy, cache de assets e aplica políticas de segurança.

Destaques Técnicos

• Implementei uma fila de jobs totalmente baseada em PostgreSQL, usando FOR UPDATE SKIP LOCKED para aquisição concorrente de jobs por múltiplos workers sem deadlocks ou necessidade de message broker dedicado.
• Modelei um pipeline resiliente de processamento de vídeos de até 2 horas, com jobs encadeados (segmentação → extração de falas → extração de promessas), retries com backoff exponencial e recuperação automática de jobs travados após crash.
• Usei LLM com reasoning para segmentar entrevistas em blocos “pergunta + resposta” de forma semântica, independentemente de limites de chunk da transcrição.
• Criei um algoritmo de merge de segmentos cruzando fronteiras de chunk, usando combinação de gap temporal, fronteiras de chunk e similaridade semântica de perguntas para reconstruir respostas contínuas.
• Estruturei o frontend em Next.js 16 com Server Actions para manter a API completamente atrás do backend, respeitando uma política CSP mais restrita e evitando exposição direta de endpoints ao browser.
• Modelei o domínio eleitoral (eleições, cargos, candidatos, mandatos, promessas, temas) de forma normalizada em PostgreSQL, permitindo queries eficientes por candidato, tema ou recorte temporal.
• Configurei um fluxo de deploy com Docker e GitHub Actions que orquestra build multi-serviço (API, frontend, worker), migrações de banco com Drizzle e publicação automatizada para ambiente de produção por trás do Cloudflare.