Gume

A produção é um único host Linux com 6 vCPU e 12 GiB de RAM rodando sete processos em contêineres: borda, web, API, worker, PostgreSQL, Redis e MinIO. Só a borda publica portas (80 e 443). O resto fica numa rede privada, e o PostgreSQL escuta apenas no loopback, para o backup.

O orçamento de memória está escrito num contrato de topologia que o CI confere: 3 GiB para o PostgreSQL, 1,5 GiB para a API, 768 MiB para o web, 512 MiB para worker e MinIO, 384 MiB para o Redis e 128 MiB para a borda. Sobram cerca de 5,25 GiB para sistema operacional, runtime de contêiner e cache de disco. O Redis roda com noeviction: se a memória acabar, ele recusa a escrita em vez de descartar um contador de limite em silêncio.

O backup roda todo dia: pg_dump, criptografia com age e envio para um bucket S3 versionado. A identidade que produz o backup só consegue gravar; quem apaga cópias antigas é outra conta, com outra credencial, e a chave privada de restauração fica fora do servidor. Cada execução grava um manifesto com hash, tamanho e a última migração aplicada, e só avisa o monitor de sucesso depois de verificar o snapshot. Se o aviso não chega em 26 horas, recebo um alerta. Um ensaio de restauração completo (dump, criptografia, upload, download da versão exata, decriptação e restore num banco vazio) roda no CI.

O deploy é um script que guarda um dump antes de cada release (mantido por 90 dias) e tem caminho de rollback. Para saúde do host, um agente pequeno lê /proc e o Docker a cada 60 segundos e manda um snapshot para a própria API, guardado por 30 dias no PostgreSQL. Escolhi isso no lugar de Prometheus e Grafana porque um stack de observabilidade completo custaria mais memória que o próprio worker.

Uma definição de campo tem UUID imutável, tipo de dono (lead, negócio, empresa ou contato), chave de máquina, tipo de valor e cardinalidade única ou múltipla. Os valores ficam em linhas ordenadas numa tabela compartilhada. Cada linha repete o tipo de dono, o tipo de valor e a cardinalidade da definição sob uma chave estrangeira composta, e um check exige que só a coluna tipada correspondente esteja preenchida. O banco recusa um texto num campo de número mesmo que a aplicação erre.

Tipo e cardinalidade não mudam depois de criados. Mudança incompatível vira campo novo mais uma migração de dados explícita, para que linhas antigas nunca sejam reinterpretadas. Apagar uma definição é lógico e preserva os valores. Referências a outro registro ou a um membro do workspace são polimórficas, então um adaptador registrado por entidade trava e valida o alvo na mesma transação; referência para outro workspace falha.

Filtros exatos e por faixa usam índices B-tree compartilhados que começam por workspace, definição e valor tipado, sem índice dinâmico por cliente. Busca aproximada não é prometida até um plano de consulta medido justificar o custo. Há limites rígidos por campo, por valor e por requisição, porque campo múltiplo multiplica linhas e o tamanho do histórico.

O isolamento entre clientes segue a mesma ideia: as tabelas carregam workspace_id, e as chaves estrangeiras compostas incluem o workspace, de modo que essas relações não conseguem apontar para dado de outro cliente nem por erro de aplicação. Por cima disso, serviços e repositórios conferem o workspace de novo depois da autorização da rota.

Cada automação tem rascunho e versões publicadas, e uma execução fica presa à versão que estava publicada quando o gatilho disparou. Editar o fluxo não muda o que já está rodando.

Espera é estado persistido. A execução vai para WAITING com um horário de retomada, e o agendador de cadências acorda as que venceram com FOR UPDATE SKIP LOCKED, para dividir o trabalho sem duas instâncias pegarem a mesma linha. Espera em dias úteis fixa a versão do calendário no momento do agendamento. Na retomada, a condição de cancelamento é avaliada contra o registro atual, então um negócio que já foi ganho não recebe o follow-up que estava agendado.

A simulação recebe só portas de leitura do workspace, um estado-sombra em memória que as ações simuladas alteram e um resolvedor de fixtures HTTP. Um passo HTTP só “funciona” se a requisição trouxer a fixture exata daquele nó; sem ela, a simulação devolve uma negação antes de qualquer adaptador de rede existir no caminho. Esperas viram tempo virtual. O resultado é um trace versionado com o registro antes e depois, e nada fica gravado: duas simulações iguais dão o mesmo resultado lógico e não deixam rastro no banco.

O plano entra aqui também. Execuções contam num contador mensal por workspace; acima do limite, a execução não é criada, o gatilho fica marcado como barrado pelo plano e não é reprocessado, e um único evento de auditoria por mês registra que o teto foi atingido.

O worker lê eventos já commitados e processa cada um numa transação que faz duas coisas juntas: insere o claim do evento (com conflito ignorado) e grava o efeito. Se o processo morrer no meio, não sobra claim sem efeito nem efeito sem claim. Execuções de automação usam lease com token e prazo; um worker que perdeu o lease não consegue gravar o resultado de um passo. O loop de polling volta imediatamente quando a última passada encontrou trabalho, para drenar fila acumulada sem esperar o intervalo ocioso.

Webhook de saída congela o corpo canônico do evento, assina cada tentativa com HMAC, tem identidade estável para o receptor deduplicar, retry com backoff, fila de mortos e reenvio manual pelo administrador. A chamada de rede acontece num consumidor próprio, fora do consumidor interno do outbox, que só mexe no PostgreSQL. Webhook de entrada valida a assinatura do endpoint, grava um recibo idempotente e o evento no outbox e só então responde 202; a execução é criada depois, de forma assíncrona.

O mesmo worker roda de hora em hora a rotina de retenção de dados pessoais, em lotes de 1.000 linhas e usando o relógio do banco: corpos de webhook e de e-mail, linhas brutas de importação e saídas de passos de automação são anulados ou redigidos em janelas que vão de 7 dias a 12 meses, e trilhas antigas são apagadas.

A sessão é um token opaco num cookie HttpOnly; o banco guarda só um digest com chave, e cada requisição resolve usuário e membership no PostgreSQL. Senha usa Argon2id. Mutações do navegador exigem Origin exata e token CSRF. Conta Google é identificada pelo sub verificado e conta Microsoft por tenant mais sub; colisão de e-mail na Microsoft falha em vez de vincular contas. Um hub único faz login e escolha de ambiente, e a passagem entre hosts usa um handoff de uso único guardado no Redis; o host de destino cria a própria sessão no PostgreSQL.

Os papéis são administrador e membro. Membros podem receber um perfil nomeado com capacidades de leitura, criação, edição e exclusão separadas para lead, negócio, empresa e contato (16 combinações). Perfil vazio, desativado ou apagado concede nada, nunca o padrão. As capacidades são resolvidas na mesma transação da requisição, sem cache, então tirar um acesso vale na próxima chamada.

Chaves de API são opacas, aparecem uma vez, têm validade obrigatória e são verificadas por HMAC com um keyring de pepper que permite rotação. Só um administrador logado por cookie cria, gira ou revoga chaves; uma chave não administra outra. Requisição com cookie e Bearer ao mesmo tempo é recusada. Todo endpoint precisa estar classificado no registro de rotas, com capacidade humana e escopo de serviço, ou a API não sobe; o OpenAPI é gerado desse registro.

O limite de requisições por chave é uma janela fixa em Redis. Um script atômico confere e incrementa cinco contadores de uma vez (versão da chave, principal, workspace, rota e classe de tráfego) ou não incrementa nenhum, e nada é devolvido depois de admitido. Se o Redis falhar, só o tráfego de chaves recebe 503; quem está no navegador continua lendo.

O servidor MCP é um processo Node.js 24 com o SDK oficial, falando por stdio. Ele se autentica com uma chave de serviço do workspace e se comporta como um cliente REST não confiável: não importa o pacote de banco, não abre conexão com o PostgreSQL e não tem regra de negócio. Workspace e autor da ação vêm sempre da autenticação, nunca do que o agente mandou.

São 58 ferramentas em seis grupos: inspeção do workspace, funis e etapas, leads, negócios, campos customizados (seções, definições e opções) e automações com suas execuções. Cada ferramenta aponta para uma operação REST canônica, declara o escopo exigido e se lê ou altera dados. Não existe ferramenta genérica de HTTP, SQL ou execução de código.

Executar e simular uma automação são ferramentas diferentes, e a simulação é classificada como leitura. Um agente com chave só de leitura pode testar fluxos à vontade sem efeito real. Mutações não são repetidas às cegas, o stdout fica reservado para o protocolo e o diagnóstico vai para o stderr já sem credenciais, prompts ou corpos de resposta. Interpretação de linguagem, planejamento e aprovação do operador ficam com o agente.