Decisões
O que decidi
nos três cases
As decisões de arquitetura dos três cases num lugar só. Filtre por projeto ou estado.
32 decisões
Plataforma de preços
8 decisões
Busca no PostgreSQL, sem Lucene
Levei a busca para full-text no PostgreSQL para deixar de manter o índice Lucene em disco fora do banco. Aceitei perder a tolerância a erros de digitação do legado para simplificar a operação da busca.
Ver no caseIngestão separada da API
Separei a coleta do PNCP em um worker para tirar esse trabalho do processo que atende os usuários. O worker tem agendamento próprio e grava no mesmo PostgreSQL que a API consulta.
Ver no caseAutenticação própria
Reaproveitei a autenticação do boilerplate com JWT, Argon2 e Redis para deixar de operar o Keycloak. Isso reduziu as dependências externas, mas deixou a manutenção dos fluxos de autenticação com a API.
Ver no caseCache Redis por módulo
Usei o Redis, que já atendia à autenticação, para evitar repetir consultas de listagem no banco. Cada módulo controla suas chaves, o prazo do cache e a invalidação quando altera os dados.
Ver no casePDF com PDFKit e react-pdf
Usei PDFKit para gerar PDFs na API Node e react-pdf no frontend, sem manter o JasperReports da aplicação Java. Os layouts passaram a ser mantidos no código TypeScript.
Ver no caseSnapshots imutáveis de cotação
Copiei os itens para cotacao_item na geração para preservar a cotação mesmo se a origem mudar ou for removida. Para os documentos, que precisam de histórico de versões, usei documento_versao com novos registros a cada finalização.
Ver no caseDados de mercado em schema separado
Separei os dados públicos do PNCP no schema licitacoes e mantive os dados das organizações no public. Assim, as tabelas de mercado ficam agrupadas à parte das tabelas que a organização usa para trabalhar.
Ver no caseMonólito modular
Mantive os módulos com rotas, services e repositories porque, com o time e o prazo que tínhamos, a camada extra de casos de uso não se pagava. Alinhei a documentação à estrutura que o código seguia.
Ver no case
Atendimento API
18 decisões
Banco único com RLS
Escolhi banco compartilhado para simplificar a operação, com RLS como garantia de isolamento entre empresas. Testei essa separação com dois tenants no PostgreSQL real via Testcontainers.
Ver no caseEmpresa vem do token assinado
Coloquei a empresa ativa no JWT assinado para usar uma única fonte de contexto nas operações autenticadas do tenant. A troca de empresa valida o vínculo e emite outro token; o webhook resolve a empresa pelo phone_number_id.
Ver no casePacotes uniformes com entidades ricas
Organizei os pacotes por funcionalidade e mantive regras nas entidades JPA para evitar camadas duplicadas no prazo do teste técnico.
Ver no caseBootstrap do administrador
Criei a empresa e o vínculo administrativo na mesma transação para evitar um cadastro sem alguém capaz de administrá-lo.
Ver no caseO webhook nunca reabre uma conversa
Criei uma nova conversa vinculada à anterior para preservar o encerramento feito pelo atendente sem perder a continuidade do histórico.
Ver no caseOutbox com worker agendado
No desenho inicial, escolhi outbox no PostgreSQL com worker interno para tornar o processamento posterior durável sem operar um broker. Retirei esse mecanismo do desenho no ADR-0011.
Ver no caseSSE com evento em processo
Planejei SSE com eventos locais para avisos unidirecionais sem adicionar um broker. A entrega ficou na API HTTP, sem SSE nem listener após commit, porque priorizei isolamento e testes no prazo do teste técnico.
Ver no caseEscopo do administrador da plataforma
Limitei o administrador da plataforma à gestão de empresas para reduzir seus privilégios sobre conversas e dados dos clientes.
Ver no caseWhatsApp Cloud API oficial
Escolhi a API oficial para reduzir riscos operacionais e implementei o recebimento do webhook com HMAC, testado só com payloads e assinaturas locais, sem mensagens reais da Meta. O envio pela Graph API ficou fora para priorizar isolamento e testes no prazo do teste técnico.
Ver no caseUma conta, várias empresas
Usei uma conta global para manter e-mail único e uma senha, com perfil e status no vínculo de cada empresa. Trocar de empresa reemite o token sem pedir a senha de novo.
Ver no caseRemoção do Outbox
Retirei o outbox do desenho porque a mensagem já fica persistida e perder um aviso de tela não justificava manter tabela e worker. O aviso após commit que o substituiria ainda não foi implementado.
Ver no caseDesativação de empresa
Reservei a desativação da empresa à plataforma porque a operação afeta todos os usuários dela. A saída voluntária do vínculo também estava prevista no ADR, mas ficou fora da entrega.
Ver no caseSó a plataforma cria empresas
Restringi a criação de empresas à plataforma para manter o cadastro de clientes sob controle do operador. Consultar e editar dependem do recurso, e o administrador de uma empresa só mexe na dela.
Ver no caseAutorização por rota e recurso
Usei o Spring Security para centralizar regras de rota e verificar acesso por recurso com @PreAuthorize e um avaliador em Java, sem criar um mecanismo próprio de autorização.
Ver no caseSem frontend
Concentrei o prazo do teste técnico na API, no isolamento e nos testes. A demonstração ficou em Scalar e um roteiro HTTP para os fluxos implementados.
Ver no caseGitFlow enxuto com GHCR e Dokploy
Separei QA e produção por branches para organizar a entrega feita sozinho. Os workflows executam testes e lint, publicam imagens no GHCR com tags por commit e acionam o Dokploy.
Ver no caseModelo de leitura para empresas inativas
Criei um modelo JPA de leitura para consultar empresas inativas e validar CNPJ sem espalhar SQL nativo nem remover o filtro padrão de empresas ativas.
Ver no caseConsulta entre empresas no login
Adiei a consulta entre empresas por usuário para preservar o isolamento na entrega, aceitando percorrer as empresas ativas durante o login. O custo cresce com o total de empresas e ainda não foi medido.
Ver no case
OPA
6 decisões
Uma pasta por seção
A landing cresceu com os arquivos no mesmo nível, e ficou difícil encontrar onde mexer. Na refatoração, cada seção ganhou sua pasta, com componentes e dados juntos.
Ver no caseCache das consultas por cinco minutos
Como os dados são públicos e iguais para todos, deixei a resposta guardada por cinco minutos. Alguns minutos de atraso são aceitáveis para uma vitrine como o observatório.
Ver no caseHero do observatório renderizado no servidor
O texto e a imagem do topo chegam prontos do servidor. Só a animação dos números roda no navegador.
Ver no caseFiltros na URL
Com os filtros na URL, um link compartilhado abre o observatório já filtrado, e o servidor monta a lista com esses parâmetros.
Ver no caseTokens de tipografia e espaço
Com tokens, tamanhos e espaçamentos se mantêm iguais entre as seções e podem ser ajustados em um só lugar.
Ver no caseAcessibilidade na busca, nos filtros e na paginação
O Lighthouse apontou botões sem nome acessível e falta de rótulos nos filtros e na paginação. Corrigi esses pontos para deixar os controles mais claros para quem navega pela interface.
Ver no case
Nenhuma decisão com esses filtros
Tente outro projeto ou outro estado.