Engenharia & stack

Por que esta página existe

As outras abas explicam o que cada número significa. Esta explica como tudo é construído — a engenharia por baixo. É a parte que não aparece na tela, mas é o que torna o resto reprodutível, automático e auditável. Para quem é técnico, é o raio-X da arquitetura; para quem não é, é a prova de que nada aqui é feito à mão num dia de inspiração.

Um princípio guia toda a stack: dado bruto entra de fonte pública, atravessa transformações versionadas, e sai como número na tela — sem nenhuma edição manual no meio. Se você reconstruir o pipeline a partir do código, chega no mesmo número.

A arquitetura num relance

As plataformas e serviços

As bibliotecas

O que o gold serve

A camada gold é o ponto de consumo. Cada domínio vira uma família de tabelas que os produtos leem:

Engenharia de dados — o lakehouse Medallion

O coração do projeto é um data lakehouse organizado pelo padrão Medallion (raw → bronze → silver → gold), que separa o dado por nível de refino:

As ferramentas

• DuckDB — o motor analítico. SQL em colunas, rápido, roda local e na nuvem com a mesma sintaxe. Faz toda a transformação entre camadas.
• MotherDuck — o DuckDB na nuvem, onde o lakehouse vive (catálogo, snapshots, time-travel). Os painéis leem do gold dele.
• DuckLake — a camada de versionamento de tabela (snapshots incrementais, evolução de schema). Permite reconstruir o estado do dado num ponto do passado.
• Cloudflare R2 — o object storage onde ficam os dados brutos e os artefatos do site (modelo bring-your-own-bucket: os dados são do projeto, não reféns de um fornecedor).
• dlt — para fontes que mudam incrementalmente e exigem normalização (a API). Para bulks estáticos grandes, DuckDB lê o arquivo direto — sem overengineering.

A convenção de nomes

As tabelas seguem uma convenção rígida que torna o pipeline legível: <camada>.<domínio>__<especialização>. O separador duplo __ distingue domínio de tabela; uma VIEW deriva barato do que muda pouco, uma TABLE materializa o que é caro de recalcular. Bronze consolida fontes; silver aplica regra; gold serve. Cada script de transformação espelha 1:1 uma tabela.

Engenharia de ML — detecção de anomalia

O detector de anomalia (descrito em detalhe na aba Gastos & CEAP) é tratado como software de verdade, não como um notebook solto:

• Camada de features separada do gold. As características que o modelo usa são computadas num módulo próprio — o gold permanece genérico e descritivo. Fato e artefato de modelo nunca se misturam.
• Ensemble reprodutível — três detectores (Isolation Forest, LOF, One-Class SVM) com semente fixa; o mesmo dado produz o mesmo resultado, sempre.
• Validação como código — null model, bootstrap e Leave-One-Positive-Out são funções testadas, com um teste de regressão que trava o build se o held-out deixar de ser honesto (capturado de um peer review real que encontrou um risco de vazamento).
• Tracking de experimentos com MLflow — cada treino registra parâmetros, métricas e o modelo versionado, com system metrics, assinatura de schema e dataset lineage. O modelo registrado tem versão (vigente + rollback).
• MLOps no DagsHub — onde os experimentos e os modelos vivem; os dados versionados via DVC.
• Os scores persistem numa tabela — o ranking do detector não fica só no log: vira tabela SQL consultável (ml.<produto>.scores__*), que os painéis cruzam com o gold. Banco separado (ml) dos dados (lakehouse), unidos por JOIN quando preciso.

A mesma máquina roda em três produtos (cota, emendas) e em três grãos (deputado, fornecedor, documento) sem alteração — a arquitetura é agnóstica ao domínio. Isso foi provado reusando o código byte a byte entre os detectores.

Exploração assistida por IA

Antes de uma análise virar painel, ela nasce em exploração — testar uma hipótese, olhar a distribuição, achar o corte certo. Isso acontece em notebooks reativos (marimo) hospedados na nuvem (molab), com uma diferença: o notebook é pareado a um assistente de IA que opera o kernel ao vivo.

Na prática, isso vira uma espécie de text-to-SQL explicável: descreve-se a pergunta em linguagem natural, o assistente escreve a consulta sobre o lakehouse, executa contra o dado real e mostra o resultado — mas a consulta fica à vista, versionada na célula, não escondida atrás de uma caixa-preta. A diferença para um “pergunte ao banco” mágico é justamente essa: cada resposta é uma query reproduzível e auditável. Quem quiser conferir lê o SQL, roda de novo, chega no mesmo número.

É a bancada de trabalho da descoberta — onde os achados das outras abas (a queima de dezembro, a ortogonalidade presença×gasto, os redutos de emenda) foram primeiro encontrados, antes de virarem pipeline produtizado. Exploração com rastro, não improviso.

Infraestrutura & automação

Nada é atualizado à mão. O conteúdo do site se mantém vivo por pipelines automatizados em GitHub Actions:

• Cascata diária — todo dia de manhã (horário de Brasília), um workflow lê as fontes, reconstrói as camadas do lakehouse, recalcula cada painel e cada índice, e publica. Cada estágio é idempotente: se nada mudou na fonte, nada muda no site (re-rodar duas vezes = zero alterações).
• Estágios desacoplados — coleta leve → classificação por IA (só se houver trabalho novo, com early-exit barato) → reconciliação → avaliação mensal. Separar evita que um estágio pesado segure um leve, e que dados velhos contaminem o próximo.
• Cadências múltiplas — diária (incremental, janela curta), semanal (refresh de cadastros) e mensal (backfill completo, que pega o que a janela curta não vê).
• Alertas em falha — qualquer quebra dispara notificação; o pipeline nunca falha em silêncio.

Versionamento & qualidade

• Git como fonte de verdade do código — todo o pipeline, cada transformação, cada build é código versionado. Um número de hoje é rastreável ao commit que o gerou.
• Fluxo de branches com revisão — nada vai para produção sem passar por pull request e revisão. A integração contínua roda testes e validações a cada mudança.
• Testes — dos parsers determinísticos (fase de votação, calendário) aos guardas científicos (o teste que trava o build se a validação do detector deixar de ser honesta, ou se um discurso for atribuído a duas pessoas).
• Validação de paridade — durante a migração do site para o lakehouse, um job comparava diariamente os números novos contra os antigos, com tolerância zero em rankings, para garantir que a fundação nova reproduzia (ou melhorava) a antiga antes de substituí-la.
• Lineage & governança de dados — o grafo de dependências do pipeline é capturado automaticamente: a extensão duck_lineage observa cada transformação SQL e emite eventos no padrão aberto OpenLineage, que alimentam um catálogo de dados no OpenMetadata — service → banco → schema → tabela, com as arestas de linhagem. O lineage é tabela a tabela e coluna a coluna: dá para perguntar “quem consome esta coluna do gold?” ou “o que quebra se eu mudar esta transformação do silver?” antes de mexer. O catálogo é autopreenchido pelo próprio pipeline — não há documentação manual de esquema que envelhece; o mapa do dado se mantém vivo sozinho.

Web — o site

O que você está lendo é um site estático servido da borda — rápido, barato, sem servidor de aplicação para manter:

• Astro — gera HTML estático a partir de componentes; o conteúdo longo (como esta página) é Markdown, os dados viram JSON no build.
• Cloudflare Pages — hospedagem na borda, com deploy automático: quando o pipeline atualiza os dados, um manifest muda e dispara o redeploy.
• Dados independentes, hospedados no site — cada painel tem seu próprio build que lê o gold e gera JSONs enxutos, guardados no R2 e baixados no build. Os números nunca ficam “congelados”: estão plugados na cascata diária.
• Observable Plot — os gráficos e dashboards interativos, renderizados no navegador a partir dos JSONs. Sem servidor de BI, sem banco vetorial no cliente.
• Busca soberana — o índice de discursos (vetores + metadados) é servido como arquivo, e a busca roda no seu navegador (palavra-chave + semântica + fusão). Só a vetorização da sua pergunta passa por uma função de borda. Nenhum servidor de busca de terceiros vê o que você procura.
• Funções de borda — pequenas funções (Cloudflare Pages Functions) para o que precisa de um segredo no servidor: vetorizar a busca, rerankear, proteger a chave. Com limite de uso e degradação graciosa.

Como o conteúdo vira publicação — o boletim

O boletim diário é parte do produto: todo dia de manhã, um pipeline verifica a sessão deliberativa do dia anterior, calcula presença/ausência a partir do gold, e agentes de IA transformam isso em conteúdo editorial — texto, apresentação e copy — que é publicado.

A filosofia, em uma linha

Linkagem

• Geral — a síntese da metodologia e da fundação de dados.
• Gastos & CEAP — o detector de ML em detalhe.
• Discursos & IA — a busca soberana em detalhe.