Arquitetura

Quatro regras foram escritas nas specs de negócio por razões que nada tinham a ver com infraestrutura. Juntas, elas decidem a fronteira do sistema — e é por isso que valem: são exigências do domínio, e o desenho que não as honra não é mais simples, é errado.

O mesmo código-fonte gera quatro perfis e usa um sistema de registro compartilhado. Serviços gerenciados reduzem tarefas de infraestrutura, mas ainda exigem configuração, monitoramento, migração, retenção e restauração. O tracejado indica dependência proposta, não disponível.

Monolito modular reduz coordenação e custo operacional para um time de uma a três pessoas, preservando atomicidade entre aprovação, documento e orçamento. Serviços separados exigiriam outro protocolo de consistência e evidência de benefício para justificar esse custo.

A carga não pede outra coisa. Microserviço resolve problema de time e de ciclo de deploy, não problema de requisição por segundo — quem resolve carga é a réplica, e a réplica é a mesma imagem rodando n vezes. Com um time de uma a três pessoas, cada serviço a mais é um pipeline, um alerta, um esquema, uma versão de contrato e um modo de falha novo — pagos todo mês, começando no primeiro mês.

O próprio Gryd.IO já pratica essa fronteira: módulo por pasta, DbContext e migrations próprios, e referência cruzada sempre para o .Core do outro módulo. O Nexio copia o padrão em vez de inventar.

As três regras da fronteira

Descartado: microserviços por domínio — saga sobre dinheiro, motor de aprovação replicado dez vezes, três mecanismos de recorte reimplementados por serviço, com um time de três pessoas. Monolito sem fronteira compilada — barato hoje e caríssimo no dia da extração, porque a fronteira que ninguém verifica não existe.

Preservar monolito modular: Organization, Catalog, Reference, Approval, Budget, Sourcing e Procurement expõem contratos sem importar Core de outro contexto. SharedKernel contém apenas tipos estáveis comuns; Platform adapta dependências externas; Persistence implementa portas e mapeia o banco compartilhado.

O NexioDbContext compartilhado simplifica transações para um time de uma a três pessoas. É uma escolha de implementação, não condição técnica absoluta: EF Core permite compartilhar transação entre DbContexts quando compartilham DbConnection e DbTransaction. Coordenar vários contextos requer esse contrato explícito e testes; conexão ao mesmo banco, sozinha, não basta.

Integridade estratégica: referências entre contextos continuam por IDs e contratos, sem navegações indiscriminadas. FK composta por tenant/empresa pode ser autorizada para invariantes importantes, com dono, justificativa, comportamento de exclusão, impacto de migração e registro de exceção. Descritores polimórficos não ganham FK fictícia; combinam validação atômica e reconciliação.

Relatórios: permitir consultas SQL/read models controlados e joins entre contextos na camada de leitura, com contrato de colunas, filtros de tenant/empresa e limites de custo. Nenhum relatório escreve em outro módulo. Evitar N+1 por chamadas repetidas; usar consultas em lote ou projeções reconstruíveis.

Os testes atuais de PersistenceBoundaryTests proíbem toda FK/navegação entre contextos, e o modelo ainda está vazio. Antes de introduzir a primeira exceção estratégica, adaptar os testes para validar o registro de exceções e as guardas. Este PR muda a decisão documental, não os testes ou o runtime.

A escolha não saiu de preferência: saiu das exigências que as specs já escreveram. Cada linha abaixo é um requisito publicado, e a coluna do meio é o que ele cobra do banco.

Caminho materializado de árvore (categoria, centro de custo, plano de contas) não entra nesta tabela: a mecânica foi escrita em termos neutros — texto com prefixo escapado — justamente para não depender de tipo proprietário. Continua assim.

Um banco de registro, não dois

A regra é simples e vale para sempre: uma verdade só. O que mais existir é derivado.

Multiempresa e a porta de saída para isolamento físico

Esquema único com tenantId em toda tabela, com o filtro global do framework. É o que o produto precisa para centenas de tenants, e é o que mantém o custo baixo enquanto os primeiros clientes são pequenos.

A porta de saída já existe no framework: o resolvedor de conexão por tenant e o orquestrador de migrations por tenant suportam banco por tenant. Para que ela continue aberta — e ela vai ser usada, porque cliente grande pede isolamento físico —, vale uma regra desde já: nenhum código assume conexão única. A conexão é sempre resolvida pelo contexto de tenant, mesmo quando a resposta é a mesma para todos. Provar o caminho uma vez, com um tenant de teste apontando para outro banco, custa pouco agora e evita redesenho depois.

Descartado: banco de documento — o domínio é invariante pura, com transação sobre dez tabelas num ato só; a consequência do erro é fiscal. Dois sistemas de registro — dobra a conciliação sem resolver nada que a réplica de leitura não resolva. Banco por tenant na v1 — paga o custo operacional do isolamento antes de existir cliente que o exija.

1. Índices, planos de consulta, limites de listagem e projeções para leituras frequentes.
2. Separar capacidade de API, Portal e Worker pelos perfis existentes; medir fila, latência e custo.
3. Réplicas de leitura ou particionamento apenas com gatilho observado de volume/tempo de manutenção.
4. Isolamento físico de tenant ou contexto somente com necessidade contratual ou operacional demonstrada, com projeto de migração e revisão das transações.

Particionar antes de dados reais aumenta operação para um time pequeno. PostgreSQL exige que chaves únicas de tabela particionada incluam a chave de partição; preservar idempotência global deve fazer parte da decisão. Separar bancos exige mover dados, rever FKs, backup, relatórios e atomicidade; não é apenas configuração.

A consequência prática cabe numa frase: o registro de serviços passa a depender do perfil. O Worker não registra controller; a API não registra job nem consumidor de fila; o Portal registra um conjunto reduzido de rotas e nenhuma delas exige token de tenant. Um teste de fumaça por perfil basta para provar que a separação não escorregou.

Descartado: tudo num processo só — é o desenho de hoje, e é o que a fila em memória força; quebra na segunda réplica. Função sem servidor para a API — partida a frio e o custo de inicialização do ORM pesam num backend transacional, e a transação da Trava 1 não ganha nada com isso. Portal como serviço com banco próprio — duplicaria o cadastro de fornecedor e a cotação, que é justamente o dado que ele existe para escrever.

Efeito obrigatório é chamada explícita dentro da transação. Eventos em memória saem depois do commit produtor e são reservados a reações cuja perda seja aceitável. Convite, aviso crítico, integração ERP e projeção obrigatória precisam de registro durável.

Gryd.IO fornece o mecanismo do outbox; cada contexto produtor possui tabela, mapeamento e migração, gravados junto do fato. O negócio define significado e versão; o consumidor deduplica junto de seu efeito. Tabela central em banco separado não cumpre atomicidade. Regras de coleta, lease e ordem estão em Eventos e outbox.

Fila gerenciada é transporte, não sistema de registro. Confirmação de envio não significa aplicação no ERP. Wolverine continua adiado: o spike é evidência limitada de compatibilidade, não adoção aprovada.

Descartado: bloqueio pessimista amplo — transforma contenção pontual em fila global. Isolamento serializável por padrão — troca corrida por tempestade de retentativa, sem ganho onde o token de versão já basta. Alterar a entidade base do framework para ganhar versão — muda todos os módulos de todos os produtos para resolver uma necessidade de um.

O isolamento dos quatro perfis deve ser demonstrado pela lista efetiva de hosted services e por execução. API e Portal não consomem filas ou executam schedulers de negócio; Worker executa os consumidores registrados; Migrator executa migrações exclusivas e termina.

Há implementações em processo na plataforma. Nem toda inscrição é TryAdd: o scheduler de GrydJobs usa registro que exige substituição explícita ou adaptação da composição. Avaliar o adaptador GrydNotifications.Scheduling existente e controlar EnableQueue e hosted services de limpeza/processamento. Trocar apenas uma interface não prova que os demais loops foram desligados.

PlatformModule ainda é ponto vazio de composição no Nexio. Adaptações, identidade de worker, leases e testes com dois processos são pendências anteriores ao primeiro cliente; não capacidades já entregues pelo pacote 5.0.2.

Por que São Paulo

Dado de compra de empresa brasileira, com nota fiscal, CNPJ e fornecedor identificado. Manter o dado no país é resposta pronta na primeira reunião de segurança do primeiro cliente médio — e a latência para o usuário é consequência gratuita. É argumento comercial antes de ser técnico.

O que isso custa e o que não prende

No começo a conta é dominada por banco e balanceador, não por computação: o Fargate de dois perfis pequenos é a menor linha da fatura. E a portabilidade real está preservada onde importa — o armazenamento de arquivo já é abstraído em três provedores pelo framework, e fila e cache ficam atrás de interface do Nexio. Trocar de nuvem custaria infraestrutura, não domínio.

Descartado: Kubernetes gerenciado — capacidade que o time não tem e não vai ter no ano. Aurora Serverless v2 na largada — tem piso de capacidade, e no cenário de poucos usuários custa mais, não menos. Azure — defensável para uma casa .NET, e sem motivo concreto (crédito, exigência de cliente, time que já opera) não paga a mudança. Nuvem do cliente ou instalação local — mudaria a fila, o agendamento e a entrega inteira; se virar exigência comercial, é revisão do ADR 3 e do ADR 7 juntos, não ajuste.

Decisão de arquitetura sem gatilho vira dogma: ninguém revisa porque ninguém sabe o que observar. Cada linha abaixo é um sinal observável — quando ele aparecer, a decisão correspondente volta à mesa; enquanto não aparecer, não volta.

Antes da implementação transacional: contratos de linha/revisão/parcela, propriedade de dados ERP, autorização empresarial, dinheiro, razão e aprovação. Compras diretas exigem ao menos entrada rastreável de demanda, estoque e programação externos; estoque e MRP não passam a ser responsabilidade do Nexio.

Antes do primeiro cliente: migrador exclusivo cobrindo Nexio e módulos Gryd; backups de banco e objetos, definição de RPO/RTO e teste de restauração; filtros de workers, revogação de sessões, retry/reprocessamento, observabilidade, limites por tenant e retenção. Mudança de esquema usa expansão/contração compatível; migração falha não inicia versão incompatível. Operação manual de reconciliação deve existir antes de automatizar integralmente o ERP.

Antes da IA: dados de decisão e alternativas, fontes e atualidade, restrições, resultados observados e avaliação com baseline. Infraestrutura dedicada de modelos, feature store e isolamento físico aguardam evidência. Contratos mínimos em Contratos transacionais.