Um Núcleo, Muitos Ofícios: A Arquitetura por Trás do Raciocínio Modular

Barbearia, clínica de psicologia, veterinária e vidraçaria não têm nada em comum — até você abrir o banco de dados. Por baixo do vocabulário de cada uma mora a mesma agenda, o mesmo cadastro de pessoa e a mesma régua de cobrança. O Raciocínio Modular é o produto que construímos em torno dessa observação, e este artigo documenta as decisões de arquitetura que fazem ele funcionar.

O problema com software de nicho

Todo ofício pequeno vive entre dois extremos ruins. Ou a operação roda em caderno, grupo de WhatsApp e planilha — um compromisso marcado em três lugares nunca está em lugar nenhum quando o cliente liga perguntando do horário — ou alguém paga por um sistema genérico demais para falar a língua do negócio, ou caro demais porque foi escrito do zero para um público de nicho pequeno.

A resposta óbvia — construir um sistema por ofício — não escala: cada vertical nova vira outro backend, outro banco, outro time de suporte. A resposta que testamos é a menos óbvia: e se o ofício fosse só uma tradução, e não uma reescrita?

A ideia: núcleo, módulos e vertical

A organização (a empresa que assina o plano) é a fronteira de tudo. Dentro dela, um núcleo cobre o que toda organização precisa — pessoa, autenticação, permissão, cobrança —, módulos são alugados um a um conforme a operação cresce, e a vertical não é código nenhum: é vocabulário, campo extra de cadastro e uma cor de destaque.

Nenhuma vertical nova pediu uma linha de código no núcleo até hoje; só um arquivo de léxico, um conjunto de campos e uma cor.

Isso significa que a mesma tabela que guarda um "compromisso" é lida como corte na barbearia, sessão na clínica de psicologia e consulta na veterinária — a tradução mora só na camada de apresentação, nunca no banco.

Quatro regras que sustentam o núcleo

1. Nenhum módulo lê tabela de outro módulo. A comunicação é só por evento — regra imposta por lint de dependência do monorepo, não por disciplina de equipe.
2. Vocabulário de nicho nunca entra no núcleo. É sempre compromisso, nunca "sessão" ou "corte".
3. A organização é a fronteira de tudo. Dado, vertical, plano, fatura, cota e cupom — tudo amarrado a uma organização, nunca espalhado por outro escopo.
4. Entitlement nunca vai no token. O JWT carrega só o usuário; a organização ativa é resolvida e revalidada contra a tabela de vínculos a cada requisição.

O isolamento entre organizações não é uma cláusula de filtro que um serviço poderia esquecer de aplicar — é Row-Level Security de verdade no Postgres, com a conexão de aplicação rodando sob uma role sem privilégio de dono, e a organização ativa fixada dentro da própria transação antes de qualquer leitura.

Módulos, um a um

À parte, por usuário e não por organização, existe ainda um cofre de senhas pessoal com criptografia de envelope (Argon2id + AES-256-GCM) — fora da régua de aluguel porque não é recurso da organização, é do usuário logado.

GLAZZ: quando o módulo vira mercado

O módulo mais ambicioso do catálogo não atende só a própria organização — ele é um mercado. GLAZZ deixa vidraçarias anunciarem peças de vidro, e permite que qualquer visitante, mesmo sem conta, busque por dimensão entre vidraçarias diferentes: a primeira vez que uma busca atravessa a fronteira de organização que o resto da plataforma trata como sagrada.

O motor não ficou preso ao vidro: uma segunda vertical de marketplace genérico já reaproveita a mesma engrenagem de escrow para qualquer categoria de produto — a aposta do núcleo, provada duas vezes.

Onde isso já roda hoje

Hoje o catálogo tem 7 módulos cobrindo 5 verticais — Barbearia, Psicologia, Veterinária, Vidraçaria e um Marketplace genérico — todas rodando sobre o mesmo núcleo, com o isolamento feito pelo banco, não pela aplicação. A infraestrutura combina Postgres com RLS (Neon), Redis Streams como espinha dorsal de evento entre módulos, Stripe Connect nos pagamentos, e deploy em Fly.io e Cloudflare Pages. Todo módulo com dado por organização nasce com um teste de isolamento real contra o Postgres antes de ir para o ar — isolamento provado, não assumido.

O produto pode ser conhecido em raciocinio-modular.pages.dev, onde é possível alternar entre verticais e ver o mesmo núcleo mudando de roupa em tempo real.

O que isso significa para o seu negócio

O nome do projeto é literal: um jeito de raciocinar sobre software de nicho decompondo-o em peças — o que é universal, o que é modular e o que é só palavra. Foi assim que veterinária entrou depois de barbearia e psicologia, e foi assim que GLAZZ, o mais complexo dos módulos, não precisou tocar em nenhum dos outros.

Essa mesma disciplina de arquitetura — separar o que é universal do que é específico do seu negócio — é o que aplicamos em qualquer projeto sob medida que desenvolvemos, dentro ou fora do ecossistema do Raciocínio Modular.