DOP
GitHub
Menu
Decisões23 decisões

Como decidimos

Um registro de decisão de arquitetura fixa o que foi decidido e descreve a arquitetura que resulta — nada mais. Estas páginas carregam o raciocínio em volta de cada uma: a pergunta como chegou, as opções que estavam na mesa, a escolhida e por quê, o que a escolha custa, e o que mudou desde então. Cada uma é escrita a partir da decisão como está hoje, e aponta para o registro que explica.

Fundações

  1. ADR-0001 Todo port tem dois adaptadores e um contrato O domínio nunca toca um fornecedor. Cada peça de infraestrutura é um port que o domínio define, com pelo menos dois adaptadores e uma suíte de contrato que ambos precisam passar — é o que deixa o mesmo binário rodar no Google Cloud e num cluster no laptop. 2026-08-29
  2. ADR-0012 Um core em Go, um BFF em Python, e uma regra entre eles Go para estado, transações, eventos e o runtime do agente; Python para a borda que fala com o cockpit e a CLI. A fronteira cabe numa frase: o BFF não tem banco nem segredo. 2026-08-30
  3. ADR-0013 Um contrato, gerado em todo lugar Um .proto por domínio é a única descrição da API. O servidor do core, o cliente da borda, a CLI e os hooks do cockpit são gerados dele, e uma mudança incompatível derruba o build em vez de aparecer em produção. 2026-08-30
  4. ADR-0015 O ambiente local roda o SDK da produção, e o Terraform é dono do resto Os emuladores do Firebase fornecem identidade e armazenamento de objetos localmente com o mesmo SDK e os mesmos arquivos de configuração da produção. A infraestrutura é criada só pelo Terraform, então não existe nada que o estado não conheça. 2026-08-30

Contas, identidade e acesso

  1. ADR-0002 A conta é dona de tudo Uma entidade, pessoal ou organização, é dona de toda integração, workspace e projeto; toda tabela carrega o seu id desde a primeira migração. Uma organização é criada na hora e se prova depois, por um registro de DNS. 2026-08-29
  2. ADR-0019 Um convite é um endereço, não uma chave Um convite não carrega segredo. O link é o id da linha, seguro para viajar em eventos, projeções e e-mails, porque aceitar exige entrar com o e-mail verificado para o qual o convite foi enviado. 2026-09-01
  3. ADR-0020 Um segundo fator, três verificadores, no core O provedor de identidade faz só o primeiro fator. O segundo — aplicativo autenticador, e-mail ou SMS — é um domínio do core, então é igual para todo provedor de identidade, roda localmente e guarda os segredos no vault. 2026-09-02
  4. ADR-0022 O core verifica uma assinatura em toda chamada Uma chamada com pessoa carrega o token da pessoa; uma sem pessoa carrega uma asserção assinada pela plataforma. A fronteira de rede é adicional — IAM do Cloud Run na nuvem, uma network policy no cluster — nunca a única garantia. 2026-09-03

Recursos, integrações e credenciais

  1. ADR-0003 A organização age; a pessoa é a autora; o agente é o committer Pushes e pull requests usam a credencial da organização, então nada quebra quando uma pessoa sai. Todo commit nomeia o desenvolvedor como author e a thread do agente como committer, então o histórico continua dizendo quem pediu e quem escreveu. 2026-08-29
  2. ADR-0009 Um tipo de recurso, um jeito de compartilhar Integrações, skills, workflows e git flows são todos recursos de uma conta, compartilhados pelos mesmos grants e pelo mesmo convite. Um tipo novo de recurso nunca toca o mecanismo de compartilhamento. 2026-08-30

Estado, eventos e comunicação

  1. ADR-0004 Toda escrita é um evento; todo o resto é projeção Toda escrita no core emite um evento imutável que carrega quem, o quê, quando e em qual contexto. O dossiê, a linha do tempo, a auditoria, o replay e as métricas são lidos desse log — nenhum deles é escrito à parte. 2026-08-29
  2. ADR-0014 Um banco só, uma outbox, e uma fila para o que falha O PostgreSQL guarda a espinha relacional, os documentos e os vetores. Toda mudança de estado grava o seu evento na mesma transação; um relay publica no NATS; uma entrega que continua falhando pousa numa única fila de dead letters com tudo o que é preciso para tentar de novo. 2026-08-30
  3. ADR-0018 Um notificador decide; um canal entrega Um consumidor da espinha de eventos decide o que notificar e para quem, a partir de uma tabela de regras. Um port por canal entrega, e cada adaptador — OneSignal, SendGrid, SMTP — resolve os próprios templates. Os casos de uso publicam eventos e nada mais. 2026-08-31

Os agentes e o seu custo

  1. ADR-0007 Threads que se endereçam, achados que se publicam A conversa de uma demanda é um conjunto de threads — o agente principal e uma por especialista — cada uma com histórico e card próprios. Os especialistas compartilham o que acharam como achados estruturados, não copiando o contexto inteiro uns nos outros. 2026-08-29
  2. ADR-0008 Medir, limitar, rotear — e desenhar o prompt para o cache Toda chamada a um modelo emite um evento de custo; toda demanda tem um orçamento que pausa em vez de matar; um roteador escolhe a classe de modelo por tipo de trabalho — nunca mais barato para o crítico. E o prompt é disposto para que a parte cara fique em cache. 2026-08-29
  3. ADR-0011 Um agente techlead por projeto, e ele nunca pausa uma demanda Quando um projeto tem duas ou mais demandas ativas, um agente orquestrador observa sobreposição, dependências e interferência, planeja uma solução e leva ao desenvolvedor uma decisão — sem parar nenhuma demanda enquanto espera. 2026-08-30
  4. ADR-0016 Um port por fornecedor de modelo, rodando onde a credencial está O runtime que fala com um modelo não vê SDK de fornecedor: envia uma conversa pelo port AgentProvider e o recurso da conta decide qual adaptador responde. Roda no core, ao lado do vault, então a credencial de um provedor nunca cruza a rede. 2026-08-31

Conhecimento e contexto

  1. ADR-0006 Três camadas de conhecimento, um pacote curado por demanda O conhecimento de um projeto são regras, um índice do seu código e uma memória de demandas passadas. Cada demanda recebe um pacote curado montado a partir deles, e a estante inteira é clonada na sandbox para o agente abrir o que precisar. 2026-08-29
  2. ADR-0021 O conhecimento do projeto é um repositório git que a plataforma hospeda Todo projeto tem um repositório raiz, que nasce com ele e é clonado em toda sandbox. Os agentes escrevem commitando; todo push é um evento; um token por demanda abre exatamente aquele repositório; o remoto do próprio usuário é um espelho. 2026-09-03

O trabalho, a sua verificação e a sua entrega

  1. ADR-0005 Sem verde, sem PR — e uma fila de merge depois do verde Um pull request só abre quando a aceitação executável passa e um crítico independente revisou, carregando a evidência. Depois do verde, uma fila por repositório reverifica cada PR contra o main atual e mergeia um de cada vez. 2026-08-29
  2. ADR-0010 O fluxo é dado: estágios tipados, composição livre, herança Os estágios têm um tipo que a plataforma sabe renderizar e executar; os fluxos os compõem livremente e são resolvidos por uma cadeia — plataforma, conta, workspace, projeto, demanda. Sem condicionais, sem linguagem de regras: um fluxo é dado que um carregador lê. 2026-08-30
  3. ADR-0017 Uma microVM por demanda, um worktree compartilhado pelas threads A fronteira dura é entre contas e entre demandas, então cada demanda ganha uma sandbox e os seus agentes dividem um workspace. A verificação nunca roda ali: roda num ambiente separado construído de um commit. 2026-08-31
  4. ADR-0023 A verificação roda num runner que constrói da fonte Um runner efêmero puxa o commit, constrói a aplicação da fonte e a sobe — nenhuma imagem do projeto é jamais construída, empurrada ou implantada. O cache da conta torna a segunda execução rápida; o runner ocupa o endereço da demanda enquanto roda. 2026-09-04