Pular para o conteúdo
Todos os projetos

Projeto autoral · SaaS multi-tenant · Analytics

PulseBoard

Um SaaS multi-tenant de gestão comercial e analytics, do banco ao deploy

Catálogo, clientes e vendas por organização, com dashboard e métricas calculados no backend, no fuso horário de cada organização. Está no ar com demo pública, documentação técnica, testes automatizados e deploy da API condicionado à CI.

  • Multi-tenancy
  • Autenticação Sanctum SPA
  • Analytics em SQL
  • Timezone por organização
  • Testes
  • CI/CD
Papel
Autor — produto, frontend, backend e deploy
Período
2026
Tipo
Projeto autoral
Stack
  • Nuxt
  • Vue.js
  • TypeScript
  • Pinia
  • Tailwind CSS
  • Laravel
  • PHP
  • PostgreSQL
  • Vitest
  • Playwright
  • GitHub Actions
  • Docker
  • Cloudflare
Dashboard do PulseBoard com KPIs comparados ao período anterior, receita diária, distribuição por status e rankings

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; owner e member tê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

Analytics de clientes com base, ativos, novos e recorrentes e ranking
Analytics de clientes — ativos, novos e recorrentes, sempre com o período anterior ao lado.
Lista de transações com filtros por status, cliente e período
Transações com filtros na URL — links compartilháveis, voltar e avançar funcionam.
Dashboard do PulseBoard em tela de celular
O mesmo dashboard no celular.

Decisões técnicas

Abordagem Como o trabalho foi conduzido.

  1. 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.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

  1. 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.

  2. 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.

  3. 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.

  4. 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.

  5. 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.

Mais trabalhos

Henrique VerriFrontend Engineer

Seu produto está crescendo? Vamos conversar.

Procuro times que tratam o frontend como engenharia — componentes com regras claras, contratos de API discutidos cedo, testes e code review fazendo parte do fluxo.