Referência de aplicação. Esta é uma arquitetura ilustrativa e uma lista de verificação de escopo, não um projeto de cliente verificado nem uma implantação medida. As tecnologias, o escopo da integração e os itens de entrega são acordados para o briefing real.
Cenário e restrições
Um produto que atende muitas organizações clientes a partir de uma única implantação. A decisão que define todo o restante é o modelo de isolamento: tabelas compartilhadas com uma coluna de tenant, um esquema por tenant ou um banco de dados por tenant. Escolher por padrão, em vez de deliberadamente, é o erro mais caro nesta categoria, porque alterá-lo posteriormente significa migrar dados de clientes em produção.
Arquitetura
Camadas e responsabilidades
| Camada | Tecnologia | Responsabilidade |
|---|---|---|
| Web | Next.js (SSR para marketing e SEO, SPA após o login) | As páginas públicas usam renderização no servidor para visibilidade nas buscas; o produto autenticado não precisa disso e permanece como uma aplicação cliente. |
| API | Go + Gin, tenant resolvido por solicitação | O contexto do tenant é resolvido a partir do subdomínio ou token antes da execução de qualquer handler e, depois, é transportado por todas as consultas. |
| Armazenamento | PostgreSQL, esquema compartilhado com escopo de tenant em nível de linha | Um banco de dados com um tenant_id em todas as tabelas pertencentes a tenants, aplicado na camada de repositório e, quando compatível, também por segurança em nível de linha como segunda linha de defesa. |
| Cache | Redis, chaves prefixadas por tenant | Sessões, limites de taxa e configuração em cache. O prefixo das chaves evita a clássica colisão de chaves de cache que vaza os dados de um tenant para outro. |
| Cobrança | Stripe ou um gateway regional | O estado da assinatura é espelhado localmente para que as verificações de permissões de acesso nunca dependam de uma chamada ativa ao provedor de pagamentos. |
| Tarefas | Processadores da fila com contexto de tenant | Trabalho agendado e assíncrono; o contexto do tenant acompanha o payload da tarefa, em vez de ser inferido no momento da execução. |
Modelo de dados
As tabelas abaixo carregam as regras das quais todo o restante depende. Errar aqui é o que transforma uma demonstração funcional em um sistema que não pode ser ampliado.
Entidades principais
| Entidade | Campos-chave, relações e regras |
|---|---|
| tenant | Registro da organização com plano, status, região e sinalizadores de recursos. Toda tabela pertencente a um tenant contém tenant_id, e nenhuma consulta pode omiti-lo. |
| usuário / associação | Um usuário pode pertencer a vários tenants com um papel diferente em cada um; portanto, a identidade é global, enquanto a permissão é definida por associação. Modelar usuário e associação como uma única tabela é o que torna impossível oferecer suporte a várias organizações posteriormente. |
| papel / permissão | Permissões concedidas a papéis, papéis atribuídos por associação e todas as verificações realizadas no backend. Ocultar no frontend é apresentação, nunca aplicação da regra. |
| assinatura / permissões de acesso | Plano, assentos, período e permissões de acesso derivadas. O acesso aos recursos consulta a permissão de acesso local, para que uma indisponibilidade do provedor de pagamentos não impeça os clientes de acessar o produto. |
| audit_log | Autor, tenant, ação, alvo e payload anterior/posterior. Dá suporte à análise de segurança e de incidentes; defina os requisitos de retenção, acesso e auditoria antes da implementação. |
| tenant_config | Configurações, identidade visual e substituições de recursos por tenant, resolvidas com uma precedência documentada sobre os padrões do plano. |
Interfaces principais
Endpoints que carregam as regras de negócio
| Endpoint | Finalidade e observações sobre concorrência |
|---|---|
| POST /api/v1/auth/login | Autentica a identidade e, em seguida, retorna as associações de tenant disponíveis; o tenant é selecionado explicitamente, em vez de ser deduzido da última sessão. |
| GET /api/v1/{resource} | Toda leitura com escopo de tenant passa por um repositório que injeta tenant_id. O escopo fica em um único lugar para que nenhum handler possa esquecê-lo: a fonte única mais comum de vazamentos entre tenants. |
| POST /api/v1/webhooks/billing | Webhook do provedor de pagamentos, idempotente com base no id do evento, atualizando localmente o estado da assinatura e das permissões de acesso. |
| POST /api/v1/tenants/{id}/invite | Fluxo de convite que cria uma associação com um papel, com limite de taxa por tenant para evitar abuso de convites. |
| GET /api/v1/audit | Consulta de auditoria com escopo de tenant e paginação, disponibilizada aos administradores do tenant como uma resposta de conformidade em autoatendimento. |
Decisões técnicas
- Esquema compartilhado com tenant_id, escolhido deliberadamente. É a opção mais barata de operar e migrar, e atende à maioria dos produtos. Quando um contrato de cliente exigir separação física, a mesma base de código poderá executar uma implantação dedicada; esse caminho é projetado desde o início, em vez de ser descoberto durante uma negociação comercial.
- Escopo de tenant aplicado em uma única camada de repositório. Depender de que cada desenvolvedor se lembre de uma cláusula WHERE é como ocorrem vazamentos entre tenants. Centralizá-lo torna difícil escrever acidentalmente a consulta insegura.
- Permissões de acesso espelhadas localmente. Consultar o provedor de pagamentos em cada solicitação adiciona latência e uma dependência rígida. O espelhamento local significa que uma indisponibilidade do provedor degrada as operações de cobrança, não o produto em si.
- Log de auditoria desde a primeira versão. Preencher retroativamente o histórico de auditoria é impossível. Confirme os requisitos de auditoria do comprador e retenha o histórico acordado desde a primeira versão.
- SSR apenas para páginas públicas. As páginas de marketing e documentação precisam de visibilidade nas buscas; o produto autenticado não precisa disso, e forçar SSR nele adiciona custo sem retorno.
Metas hipotéticas de design
Os números abaixo são exemplos hipotéticos de planejamento de capacidade, não resultados medidos de clientes, uma recomendação de dimensionamento validada ou um SLA. Defina metas de aceitação específicas do projeto após definir a carga de trabalho, os dispositivos, os dados, o hardware e as dependências de terceiros; verifique-as por meio de um piloto e de testes de carga antes de assumir uma meta de produção.
Metas de capacidade e desempenho
| Meta | Valor e premissa |
|---|---|
| Latência da API | p95 inferior a 250 ms para leituras com escopo de tenant e índices compostos corretos iniciados por tenant_id. |
| Isolamento de tenants | Exigir uma suíte automatizada que tente acessar dados entre tenants em todos os endpoints e interrompa a compilação diante de acesso não autorizado. A implementação deve passar por essas verificações; esta referência não é evidência de um teste de segurança concluído. |
| Onboarding | Novo tenant provisionado em segundos, pois se trata de uma linha e um registro de configuração, e não de trabalho de infraestrutura. |
| Escala | Dimensionado para alguns milhares de tenants em uma única instância PostgreSQL; além disso, o caminho consiste em réplicas de leitura e depois fragmentação por tenant, planejado, mas não construído prematuramente. |
O que a entrega inclui
- Código-fonte do frontend Next.js, do backend Go e do painel administrativo no seu repositório
- Esquema do banco de dados com escopo de tenant, índices e tabelas de auditoria documentados, além do histórico de migrações
- Suíte de testes de isolamento entre tenants executável na sua CI
- Integração de cobrança, tratamento de webhooks e documentação das permissões de acesso
- Notas de implantação para Docker e Nginx, configuração do ambiente e procedimento de backup e restauração
Planejando isso para sua empresa
Os módulos acima são um ponto de partida, não um pacote fixo. Normalmente reduzimos a primeira versão a um fluxo principal e um fluxo administrativo, expandindo depois que o uso real mostrar onde estão de fato a carga e os casos extremos. Envie um briefing com escopo e nós o mapearemos nesta arquitetura, informando quais partes você ainda não precisa.