O que é o PulseBoard
Uma aplicação para acompanhar a operação comercial de um negócio: quanto vendi neste período comparado ao anterior, quais produtos puxam a receita, quantos clientes voltaram a comprar.
- Organizações e papéis — o cadastro cria o usuário, a organização e a membership
owner;owneremembertêm permissões diferentes, aplicadas pela API. - Produtos e clientes — CRUD com busca, detalhe com métricas de venda e exclusão que preserva o histórico.
- Transações — histórico de vendas somente leitura, com itens e preço no momento da venda.
- Dashboard e analytics — receita, pedidos, ticket médio e clientes, receita por dia, semana ou mês, rankings e distribuição por status, sempre com o período anterior ao lado.
- Estado na URL — período, filtros, ordenação e paginação ficam na query string.
Telas



Decisões técnicas
Abordagem Como o trabalho foi conduzido.
- Etapa 01
Isolamento em camadas
Multi-tenancy
Banco compartilhado com organization_id em toda tabela de domínio. O header X-Organization-Id seleciona o contexto, mas não autoriza sozinho — o middleware valida a membership a cada requisição.
- Sessão (401), membership (403), route model binding (404, sem revelar existência), Form Requests (422), models e policies.
- O tenant nunca vem do cliente — organization_id no payload ou na query é proibido.
- Testes dedicados verificam que dados de outra organização não aparecem em listagens nem alteram números agregados.
- Etapa 02
Sanctum SPA
Autenticação
Sessão em cookie httpOnly, Secure e SameSite=Lax, com CSRF via XSRF-TOKEN e retry automático em 419. Nenhuma credencial em localStorage; o Pinia guarda só o estado de UI.
- Consequência assumida — front e API precisam estar no mesmo site (app. e api. sob henriqueverri.dev).
- CORS restrito à origem exata do front e rate limit em login e cadastro.
- Etapa 03
Uma definição de métrica
Analytics
Tudo agregado em SQL no backend, um service por endpoint; o front não recalcula nada. O resumo de cada tela é o mesmo número do dashboard por construção.
- Período anterior de mesma duração em todas as métricas.
- Dinheiro como string decimal na API, nunca float.
- Número fixo de consultas por endpoint, travado por teste.
- Consistência entre endpoints testada — receita do dashboard igual à soma da série temporal e do ranking.
- Etapa 04
Calendário do negócio
Timezone
O banco guarda UTC; o calendário de negócio é o fuso IANA da organização. Os buckets de dia, semana ISO e mês são agrupados no fuso local pelo PostgreSQL, com horário de verão correto — testado na CI.
- O cliente nunca escolhe a timezone; o front calcula "hoje" e os presets no mesmo fuso.
- Etapa 05
CI antes do deploy
Entrega
GitHub Actions roda Pint e PHPUnit em PostgreSQL, ESLint, typecheck, Vitest, build estático e um smoke E2E com Playwright contra o build de produção.
- Front no Cloudflare Pages; API em Docker no Render, publicada só depois que os checks passam.
- Se o start do container falhar, ele não aceita tráfego e a versão anterior continua no ar.
Decisões E seus trade-offs.
- 01
Sanctum SPA com cookie httpOnly
Por quê: Credencial fora do alcance de JavaScript, CSRF nativo e nenhum BFF extra.
Trade-off: Front e API precisam compartilhar o domínio registrável; previews do Pages não autenticam.
- 02
Nuxt como SPA estática
Por quê: A sessão é um cookie da API; SSR não agregaria valor e exigiria um servidor Node.
Trade-off: Sem renderização no servidor — irrelevante para uma área autenticada.
- 03
Multi-tenancy por organization_id
Por quê: Simples de operar, com isolamento garantido em camadas e coberto por testes.
Trade-off: O isolamento depende da aplicação, não do banco — sem schema por tenant nem RLS.
- 04
Analytics agregadas no backend
Por quê: Uma definição de métrica para todas as telas; o front só apresenta.
Trade-off: Cada requisição consulta o banco, sem cache.
- 05
Playwright contra o build de produção
Por quê: Valida o artefato que vai para o Pages, com API e PostgreSQL reais.
Trade-off: Um smoke do fluxo principal, não uma suíte E2E extensa.
Arquitetura
Navegador
│
▼
Nuxt 4 SPA estática ───────── Cloudflare Pages · app.henriqueverri.dev
página → composable → repository → useApiClient
│
│ REST + cookie de sessão (Sanctum SPA, CSRF) + X-Organization-Id
▼
API Laravel 12 ────────────── Render · Docker · api.henriqueverri.dev
middleware de tenant → Form Request → Controller
→ Policy → Service (agregações SQL) → API Resource
│
▼
PostgreSQL ────────────────── Supabase
No frontend, nenhum componente faz HTTP direto: o acesso passa por repositories e pelo useApiClient, que centraliza credenciais, header de organização, CSRF e normalização de erros. Pinia só para a sessão; dados de tela via useAsyncData com chave por organização.
Resultado O que mudou.
- Demo pública em app.henriqueverri.dev, com contas owner e member para explorar a diferença de permissões.
- Isolamento entre organizações aplicado em seis camadas e verificado por testes dedicados.
- Números consistentes entre telas por construção, e conferidos por testes de consistência cruzada.
- Documentação técnica de arquitetura, API, testes e deploy no repositório.
Números documentados
~2–45 ms
Consultas de analytics em 30 dias
Por consulta, via EXPLAIN ANALYZE no PostgreSQL 16, num banco descartável com 200 mil transações e 500 mil itens.
Fonte: docs/architecture.md, seção Performance
1 a 4
Consultas por endpoint de analytics
Número fixo, independente de volume, período ou granularidade.
Fonte: README, travado por AnalyticsQueryBudgetTest
376
Testes da API
PHPUnit — auth, isolamento entre organizações, CRUD, analytics, timezone e operação.
Fonte: README do repositório, seção Testes · Setembro de 2026
168
Testes do frontend
Vitest e @nuxt/test-utils — utilitários, cliente de API, sessão, composables e páginas.
Fonte: README do repositório, seção Testes · Setembro de 2026
Escopo e próximos passos
O PulseBoard é um projeto autoral, construído como produto: não há empresa nem clientes reais por trás dele. As transações vêm de um gerador de dados de demo, a infraestrutura usa planos gratuitos (a API pode levar até cerca de um minuto no primeiro acesso depois de um período ocioso) e a interface é só em português.
O que a arquitetura atual pediria primeiro para operar com tráfego real — e ainda não está implementado:
- Observabilidade: rastreamento de erros, latência por endpoint e alertas, além dos logs e do health check atuais.
- Rate limiting além da autenticação, começando pelos endpoints de analytics.
- Staging e backups gerenciados, para validar migrations antes de produção.
- Cache ou pré-agregação de analytics para organizações grandes — o caminho indicado pelas medições, em vez de novos índices.



