Sistema SaaS multi-tenant desenvolvido para corretores de café atuarem na intermediação de vendas entre produtores e compradores, com isolamento completo de dados por corretora (banco de dados dedicado por tenant) e provisionamento automatizado de novos clientes por subdomínio.
Stack principal
Camada Tecnologia Backend PHP 8.2 + Laravel 12 Frontend server-side Blade + Alpine.js 3 Estilização Tailwind CSS 4 (via plugin oficial do Vite) Build Vite 7 Banco de dados PostgreSQL, com um banco isolado por tenant Cache, sessões e filas Redis Multi-tenancy Pacote stancl/tenancy (banco por tenant + identificação por subdomínio) Geração de PDF barryvdh/laravel-dompdf e FPDF Importação/exportação de planilhas maatwebsite/excel Ambiente Containerizado com Docker
Arquitetura
- Camadas Controller → Service → Repository, com controllers enxutos e toda a comunicaçãos repositórios
- Services responsáveis por regras de negócio complexas, orquestração entre múltiplos repositórios >
- Isolamento de dados por tenant via banco separado (sem coluna de tenant nas tabelas de negócio e
- Valores monetários armazenados como inteiros em centavos, nunca em ponto flutuante
- Paginação e busca sempre server-side (skip/take + LengthAwarePaginator)
- Componentes Blade reutilizáveis para elementos de UI recorrentes (inputs, botões, cards, tabelas)
- Processamento assíncrono via filas Redis (envio de e-mails, provisionamento de tenant, jobs de importação)
Principais módulos implementados
- Autenticação e recuperação de senha por tenant
- Gestão de clientes, produtores e compradores, incluindo importação em massa via planilha
- Cadastro de produtos e controle de qualidade do café (amostras, catação, peneiras, tipos de bebid
- Registro e acompanhamento de vendas
- Módulo financeiro: contas a pagar/receber, plano de contas e livro caixa
- Relatórios de vendas e relatório de mercado, com link público compartilhável e exportação em PDF
- Modelos de impressão configuráveis por corretora
- Central de notícias interna (blog corporativo) com fluxo de publicação e envio de e-mail aos usuários
- Sistema de chamados/suporte com mensagens, anexos, prioridade e departamento
- Notificações internas (sino) e por e-mail para eventos do sistema
- Gestão de corretoras (tenants) com onboarding automatizado e landing page configurável
Qualidade e testes
- Suíte de testes com PHPUnit, separada em testes de Repository, Service e testes de fluxo
- Uso de mocks para isolar regras de negócio dos Services em relação à camada de persistência
- Padronização de nomenclatura em português em todas as camadas (models, controllers, services, enu
- Uso de Enums tipados para status e categorias de domínio (status de chamado, tipo de notificação, prioridade, etc.)
Principais desafios técnicos
Multi-tenancy com banco por tenant, não com coluna discriminadora.
A decisão de isolar cada corretora em um banco PostgreSQL próprio elimina de raiz o risco mais comum de de dado entre clientes por um filtro esquecido em uma query. O custo dessa segurança é operacional: toda migration de negócio precisa rodar de forma idempotente em N bancos, o provisionamento de migrations e popular dados iniciais em um único fluxo confiável, e a conexão ativa do Eloquent precisa trocar corretamente por subdomínio a cada requisição.
Consistência financeira.
Armazenar valores monetários como inteiros em centavos evita erro de arredondamento em cálculos de como no livro caixa um tipo de bug que normalmente não aparece em teste manual, só em produção ou em algum extrato que não fecha.
Processos assíncronos com efeito colateral real.
Provisionamento de tenant, envio de e-mail e importação de planilha rodam em fila Redis.
Importação em massa via planilha.
Validar linha a linha, reportar erro por linha sem abortar a planilha inteira e não estourar memória.
Link público de relatório sem expor a chave interna.
O relatório de mercado tem link público compartilhável usando uma coluna UUID própria para essa finalidade interna (bigint incremental) fora de rotas públicas evita enumeração de recursos e vazamento devolume de dados pelo ID sequencial.
Pontos de destaque
- Disciplina arquitetural sustentada por decisões documentadas (ADRs), não apenas declarada em text
- Modelagem de domínio fiel ao negócio real: saca de 60kg, classificação ABIC, comissão percentual e de contrato.
- Segurança por isolamento físico de dados.
- Sistema completo além do core de vendas: chamados, notícias internas e notificações.
- Nomenclatura e enums tipados consistentes em português em todas as camadas do código.