Engenharia/Arquitetura

Monólito modular primeiro: como estruturo um SaaS do zero sem me arrepender depois

Microsserviços resolvem problemas que um produto novo ainda não tem. As convenções que uso para começar com um monólito bem dividido, que aguenta crescer e não vira um novelo.

Murilo Anzini 3 min de leitura

Toda vez que começo um produto do zero, a tentação aparece: "já vamos fazer em microsserviços, para escalar". E toda vez a resposta é a mesma: escalar o quê? Um produto novo não tem problema de escala. Tem problema de descobrir se alguém quer usá-lo. A arquitetura certa para essa fase é a que deixa você mudar de ideia rápido.

Para mim, essa arquitetura é um monólito modular: um único deploy, um único banco, mas dividido por domínio com fronteiras claras. Simples de operar hoje, fácil de quebrar amanhã se precisar.

Por que não microsserviços logo de cara

Microsserviços trocam complexidade de código por complexidade de operação. Você ganha deploys independentes e times autônomos, e paga com rede entre serviços, consistência eventual, observabilidade distribuída, versionamento de contratos e uma infraestrutura que exige gente para cuidar.

Esse preço vale quando você tem muitos times pisando no mesmo código ou partes do sistema com necessidades de escala muito diferentes. Num produto com um time pequeno e poucas centenas de usuários, é só custo.

A pergunta útil não é "monólito ou microsserviços?", e sim "onde estão as fronteiras do meu domínio?". Se as fronteiras forem boas, extrair um serviço depois é uma tarefa. Se forem ruins, nem microsserviços salvam.

As convenções que sustentam o monólito

Um monólito só vira novelo quando não tem regras. Estas são as que mais me ajudam, usando NestJS como exemplo (a ideia vale para qualquer stack):

1. Um módulo por domínio

Cada domínio de negócio vive na sua pasta, com controller, service, entidades e testes juntos. Não existe pasta services/ com tudo misturado.

src/modules/
  auth/
  billing/
  projects/
  reports/
  mail/

2. Módulos não são globais

Se o módulo de relatórios precisa do módulo de projetos, ele declara o import. Parece burocracia, mas é o que torna as dependências visíveis. Quando o grafo começa a ficar estranho (todo mundo importando todo mundo), você enxerga antes de virar problema.

3. Um contrato HTTP único

Toda resposta sai no mesmo envelope e todo erro no mesmo formato. Eu uso { data, meta } para sucesso e Problem Details para erro, aplicados globalmente. O controller retorna o dado cru e não se preocupa com formato.

reports.controller.ts
@Get(':id')
async findOne(@Param('id') id: string, @CurrentBusinessId() businessId: string) {
  // Só o dado: o envelope { data, meta } é aplicado por um interceptor global
  return this.reports.findOne(businessId, id)
}

O front agradece: um único cliente HTTP, um único tratamento de erro.

4. Erros esperados têm tipo e código

throw new Error('não encontrado') vira 500 e esconde a intenção. Erro esperado é uma classe (NotFoundError, BusinessRuleError) com um código estável, que o front pode traduzir e o suporte pode procurar no log.

5. Testes de contrato

Para cada rota, um teste grava a forma da resposta num arquivo de referência. Mudou o contrato sem querer? O teste falha. Mudou de propósito? Você regrava e revisa o diff do JSON no PR. É barato e pega exatamente o tipo de regressão que quebra o front em silêncio.

Multi-tenant desde o primeiro dia

Se o produto é B2B, uma regra vale ouro: o tenant nunca vem do cliente. O id da empresa sai do vínculo do usuário autenticado, num decorator, e todo acesso a dado de domínio filtra por ele. Parece óbvio, mas é o tipo de coisa que, se não nasce na fundação, vira auditoria dolorosa depois.

Documentação que vive junto do código

Arquitetura que só existe na cabeça de alguém não é arquitetura, é folclore. Mantenho uma pasta docs/ no repositório com:

  • Visão geral da arquitetura e as decisões que a sustentam;
  • Checklists (o que toda rota nova precisa ter);
  • Dívida técnica conhecida, para ninguém assumir que algo funciona quando não funciona;
  • Decisões (ADRs), curtas, com o contexto de quando foram tomadas.

Cada doc tem uma data de "verificado em". Mudou o comportamento? Atualiza o doc no mesmo commit. É isso que permite que outra pessoa (ou um agente de IA) trabalhe no código sem quebrar as regras.

Quando sair do monólito

Os sinais de que chegou a hora de extrair um serviço são concretos:

  • Um módulo precisa escalar de forma muito diferente do resto (processamento pesado, filas, picos);
  • Times diferentes estão constantemente se bloqueando no mesmo deploy;
  • Um domínio tem requisitos de isolamento (segurança, compliance) que justificam a separação.

Se as fronteiras foram respeitadas, extrair esse módulo é mover uma pasta e trocar chamadas de função por chamadas de rede. Se não foram, você descobre que o "módulo" conversa com metade do sistema.

Resumo

Comece simples, mas com disciplina. Um monólito modular com módulos por domínio, dependências explícitas, contrato único, erros tipados, testes de contrato e documentação viva te dá a velocidade de que um produto novo precisa e a estrutura para crescer quando (e se) o produto pedir.

#arquitetura#nestjs#saas#monolito

Murilo Anzini

Engenheiro de software com cabeça de produto, olho de dados e repertório de marketing. Analiso, crio e evoluo a jornada completa de um produto e da empresa por trás dele.

Sobre mim

Ebook gratuito

Criando infoprodutos de valor

A metodologia que uso para unir produto, marketing e vendas na criação de infoprodutos: do jeito que startups validam hipóteses, entendem necessidades e constroem o que o mercado quer comprar.

  • Entender o cliente e definir as hipóteses iniciais
  • Construir e testar um MVP enxuto
  • Medir o progresso e validar com dados
  • Saber a hora e o jeito de pivotar
Baixar grátis PDF · 23 páginas · sem cadastro