VOWGRID

Contexto

Eu queria um projeto que tratasse ações disparadas por IA como um problema real de sistema, não como um fluxo de demo. O VOWGRID virou isso: uma camada de confiança entre agentes e ações no mundo real, com checagem de política, aprovação, rastreio de execução, recibos e visibilidade de rollback. O repositório agora fica privado enquanto a superfície do produto amadurece, mas o desenho do sistema continua forte o bastante para documentação pública.

Problema

A maior parte dos projetos com agentes foca no que o modelo consegue decidir. Eu quis focar no que acontece depois. Quando uma ação pode tocar um conector real, o projeto precisa de simulação, avaliação de política, auditabilidade, execução com fila e uma control plane legível.

Restrições

O produto precisava explicar um ciclo completo de ação, não só um endpoint.
O backend precisava de fronteiras claras dentro de um monolito modular.
O setup local precisava ser reproduzível com Docker, migrations do Prisma e seed de desenvolvimento.
O web app precisava funcionar contra a API real, mas também continuar útil quando o backend estivesse indisponível.

Prova centralSimulação + política + aprovação + execução

Sinal do repositórioMonorepo com docs, contratos e runbook

Preocupação operacionalRecibos, auditoria e visibilidade de rollback

Arquitetura

monorepo
  -> apps/api (Fastify + Prisma + BullMQ)
  -> apps/web (control plane em Next.js)
  -> packages/contracts (schemas compartilhados)
  -> packages/ui (primitivos compartilhados)
  -> docs + infra

01Propor a ação

O sistema guarda a intenção como draft em vez de saltar direto para execução, o que mantém a control plane legível.

02Simular antes de tocar conectores

A simulação mostra efeito colateral previsto e shape de payload antes que qualquer conector mude algo no mundo externo.

03Avaliar política e aprovação

Regras, papéis e estado de aprovação viram gates explícitos, não detalhe escondido de implementação.

04Executar via fila

BullMQ assume retries, visibilidade e transições de execução para que a operação continue inspecionável depois do caminho feliz.

05Emitir recibos e rollback visível

A execução termina com evidência: recibos, trilha de auditoria e visibilidade de como o rollback seria tratado se a ação precisasse ser desfeita.

Decisões e trade-offs

Eu mantive o backend como monolito modular porque simplicidade operacional importava mais do que espalhar serviços.
O modelo de confiança é explícito em camadas: primeiro simulação, depois política, depois aprovação, depois execução.
Eu usei BullMQ porque execução enfileirada e visibilidade de retry fazem parte da história do produto.
O repo inclui docs e fluxo funcional porque um produto de confiança precisa ser compreensível antes de ser impressionante.

O que funcionou

O projeto tem uma identidade de sistema muito mais forte do que um repo genérico de "AI agents".
O runbook, o seed e o setup local com Docker tornam o sistema fácil de avaliar tecnicamente.
A estrutura de monorepo mantém contratos, UI, API e docs alinhados em torno do mesmo ciclo de intent.

O que ainda está incompleto

O processamento de rollback ainda não foi fechado por um worker dedicado.
Ainda falta autenticação JWT para o dashboard.
Gestão de API key para usuários finais e cobertura E2E mais forte ainda precisam entrar.

Evidência

Fluxo validado do workspaceWorkspace privado do VOWGRID

Ciclo do intent:
- criar draft
- propor
- simular
- avaliar política
- aprovar
- executar
- gerar recibo
- inspecionar visibilidade de rollback