Todos os cases
~/cases/[classificado]/alicerce
confidencial · NDAPlataformas & CRMsMajoritárias estaduaisdez 2025 → set 2026Concluído

P-07

Alicerce

Captação, militância e CRM de mobilização numa só base, com o Postgres decidindo quem é quem.

cliente████Pré-campanha majoritária de abrangência estadual

Plataforma digital de uma pré-campanha estadual: páginas públicas de apoio, portal do ativista com link de indicação e ranking, e um painel administrativo que funciona como CRM. A camada de mobilização unifica cada pessoa num perfil único pelo telefone, registra a jornada por página e o histórico de cada campo, calcula um Lead Score orientado a eventos e mede o funil por página e por UTM. Tudo acontece no banco, por triggers e funções SECURITY DEFINER, com RLS em todas as tabelas, cadastro público só por Edge Function com CAPTCHA, login com limite de tentativas e travas contra exclusão em massa. Cerca de dez meses em produção.

221
Migrations
177
Policies de RLS
38
Edge Functions
67
Tabelas
  • supabase
  • postgres
  • rls
  • edge
  • react
  • pwa
  • crm
  • anti-bot
  • rate-limiting
  • lgpd
architecture.pt.svgampliar ↓

01Visão geral

O Alicerce é a plataforma digital de uma pré-campanha majoritária de abrangência estadual. Ele junta três coisas que normalmente vivem em ferramentas separadas: as páginas públicas onde as pessoas declaram apoio, um portal para a militância acompanhar suas indicações e baixar materiais, e um painel administrativo que funciona como CRM da campanha.

Quem chega pela página pública preenche um formulário curto e vira apoiador. Quem quer fazer mais se cadastra como ativista: ganha login, um link pessoal de indicação, materiais de divulgação e uma posição no ranking. A coordenação usa o painel para ver de onde vem cada cadastro, unificar a mesma pessoa que apareceu em várias páginas, pontuar o engajamento de cada contato e mandar e-mails segmentados.

O sistema ficou cerca de dez meses em produção (dezembro de 2025 a setembro de 2026), passando por várias ondas de páginas temáticas, eventos e plenárias digitais. Na reta final, a página inicial passou a redirecionar para o site oficial da campanha, e o Alicerce seguiu como back-office: os formulários do site novo continuaram chegando ao mesmo CRM por uma API autenticada.

02O problema

  • A mesma pessoa em dez lugares. Cada página temática, evento ou plenária tinha seu próprio formulário e sua própria tabela. Sem uma chave comum, não dava para saber quantas pessoas reais a campanha tinha, nem a jornada de cada uma.
  • Apoio não é tudo igual. Quem se cadastrou uma vez é diferente de quem participou de três eventos e trouxe dez pessoas. A coordenação precisava priorizar contatos sem montar planilhas à mão.
  • Atribuição. Saber se um cadastro veio de um link de ativista, de um QR code impresso, de um e-mail ou de uma UTM de rede social, e onde cada página perdia gente no caminho.
  • Formulário público, base valiosa. Uma base de contatos de campanha é alvo de robôs, de cadastros falsos e de tentativas de leitura ou exclusão em massa. Ao mesmo tempo, é dado pessoal sob a LGPD.
  • Ritmo de campanha. Páginas novas toda semana, regras mudando, equipe pequena e boa parte da base construída num gerador de código assistido por IA, com centenas de migrations acumuladas.

03A solução

  • Captação pública: formulário leve com município por combobox (lista do IBGE), CAPTCHA Turnstile, tela de sucesso com três caminhos (compartilhar, virar ativista, entrar no canal de mensagens) e páginas temáticas com formulário próprio.
  • Área do Ativista (PWA instalável): link de indicação com QR code, modelos de mensagem prontos, galeria de materiais, posição no ranking e top 10 de ativistas.
  • Gamificação no painel: distribuição por níveis, ranking por estado e por cidade, ativistas do dia e placar de sequência diária de atividade.
  • Fluxo de entrada de ativistas: cadastro direto aprovado na hora, com conta provisionada e e-mail de ativação; pedidos vindos da página de sucesso caem numa fila de aprovação no painel.
  • CRM de perfil único: cada pessoa vira um perfil identificado pelo telefone normalizado, com a jornada de cadastros por página e o histórico de cada campo alterado (nome, e-mail, UF, município, bairro, CEP).
  • Lead Score: pontuação somada a partir de um catálogo de ações configurável, com faixas de "temperatura", pontos automáticos por cadastro em cada página e por indicação recebida, e importação por CSV restrita a ações externas (e-mail, mensagens, redes). Causas marcadas como sensíveis entram num fluxo de cuidado e não pontuam.
  • Tracker de captação: gerador de UTMs em cinco dimensões, origem de cada cadastro e funil por página e por UTM (visita → início → envio), com atribuição de tráfego externo.
  • Painel administrativo: 20 telas, entre KPIs com mapa coroplético do Brasil e drill-down por município no estado-foco, gestão de apoiadores e ativistas, ranking de indicações com análise de Pareto, e-mail marketing com agendamento e métricas, eventos, petições, aniversariantes e relatórios em PDF.
  • Modo Privacidade: um botão no cabeçalho (admin e ativista) que borra nomes e números na tela, para apresentar o painel em reunião ou compartilhar a tela sem expor dados.
  • Perfil único por telefone: uma função de ingestão no banco alimentada por triggers e por backfill idempotente, com jornada por página e histórico campo a campo.
  • Lead Score orientado a eventos, com deduplicação por índice único parcial e causas sensíveis fora da pontuação.
  • Cadastro público só por Edge Function com Turnstile e whitelist de colunas; INSERT anônimo revogado na tabela.
  • Login por Edge Function com limite de 5 falhas por IP e 8 por e-mail em 2 minutos e IP guardado só como hash.
  • Auditoria com snapshot de cada exclusão e trigger que bloqueia DELETE de mais de 5 apoiadores por statement.
  • 221 migrations, 67 tabelas e 177 policies de RLS; 38 Edge Functions; 49 rotas com carregamento sob demanda.

04Arquitetura

arquitetura real · passe o cursor nos nós
Ler o diagrama como lista (15 componentes, 14 conexões)

Componentes

  • Clientes: Landing pages públicas<br>formulário leve + LPs temáticas, Área do Ativista<br>(PWA), Painel administrativo<br>CRM + relatórios
  • Edge Functions (Deno) · 38: login<br>rate limit IP + e-mail, submit-form<br>captcha + whitelist, ativação<br>link assinado HMAC, webhooks de entrada<br>segredo · Svix
  • Postgres · RLS: supporters<br>audit + trava de DELETE, perfil único<br>crm_ingest, Lead Score, funil<br>LPs · UTMs · page_events
  • Supabase: Auth<br>e-mail + senha, PostgREST + RPCs<br>is_admin / has_role, PG

Conexões

  • Clientes → SPA estática<br>Vite + Service Worker<br>Cloudflare Turnstile
  • SPA estática<br>Vite + Service Worker<br>Cloudflare Turnstile → login<br>rate limit IP + e-mail
  • SPA estática<br>Vite + Service Worker<br>Cloudflare Turnstile → submit-form<br>captcha + whitelist
  • SPA estática<br>Vite + Service Worker<br>Cloudflare Turnstile → PostgREST + RPCs<br>is_admin / has_role (JWT do usuário)
  • login<br>rate limit IP + e-mail → Auth<br>e-mail + senha
  • ativação<br>link assinado HMAC → Auth<br>e-mail + senha
  • submit-form<br>captcha + whitelist → supporters<br>audit + trava de DELETE (service role)
  • PostgREST + RPCs<br>is_admin / has_role → funil<br>LPs · UTMs · page_events
  • PostgREST + RPCs<br>is_admin / has_role → perfil único<br>crm_ingest
  • supporters<br>audit + trava de DELETE → perfil único<br>crm_ingest (trigger)
  • perfil único<br>crm_ingest → Lead Score (trigger)
  • Resend · n8n · GA4<br>formulários externos → webhooks de entrada<br>segredo · Svix (webhook autenticado)
  • webhooks de entrada<br>segredo · Svix → supporters<br>audit + trava de DELETE
  • PG → Resend · n8n · GA4<br>formulários externos (pg_net / e-mail / GA4)

O front é uma SPA React servida como estático, sem servidor próprio. Tudo o que exige privilégio passa por uma de 38 Edge Functions em Deno ou por funções Postgres SECURITY DEFINER chamadas como RPC. O banco é a fonte de verdade: a unificação de perfis e a pontuação acontecem em triggers, não no cliente, então qualquer porta de entrada (formulário próprio, webhook de chatbot, API do site externo, importação) produz o mesmo resultado.

05Por dentro

Backend e dados
  • 221 migrations versionadas, 67 tabelas no schema público (segundo os tipos gerados), 177 declarações CREATE POLICY e 33 triggers distintos.
  • Papéis em tabela própria: user_roles com o enum app_role e a função has_role() SECURITY DEFINER; nada de papel guardado no perfil do usuário.
  • Ingestão única (crm_ingest), chamada por triggers em supporters e na tabela de formulários de eventos, e por funções de backfill idempotentes para a base histórica (inclusive em lotes por keyset para a tabela maior). Ela normaliza o telefone, acha ou cria o perfil, registra no histórico cada campo que mudou e grava o evento da jornada com UNIQUE (profile_id, form_slug), o que garante um registro por pessoa e por página mesmo se o mesmo cadastro for reprocessado.
  • Lead Score orientado a eventos: a nota é a soma de crm_score_events. Eventos automáticos carregam source='auto' e um source_ref; um índice único parcial em (action_slug, source_ref) impede pontuar duas vezes o mesmo cadastro ou a mesma indicação, enquanto os eventos importados por CSV deduplicam por pessoa, ação e dia (no fuso de São Paulo).
  • Funil de páginas: page_events recebe eventos anônimos do cliente e um trigger BEFORE INSERT resolve a página e a UTM; a leitura fica restrita a administradores e exposta por RPCs agregadas (get_funnel_overview, get_funnel_detail, get_utm_funnel).
  • RPCs paginadas no servidor para as listas grandes (perfis, apoiadores, CRM geral), com filtros e ordenação no Postgres, e um utilitário no front que pagina com .range() quando é preciso buscar a base inteira acima do limite de linhas do PostgREST.
  • Integrações por Edge Functions: e-mail transacional e de campanha pelo Resend (com webhook de eventos e sincronização de métricas), automações em n8n, chatbot de mensagens, Google Analytics 4 (dados históricos e tempo real), proxy de CEP, ingestão de eventos e de formulários externos.
  • Jobs: pg_cron para limpeza diária de logs de e-mail e pg_net para encaminhar cadastros de páginas de evento a um endpoint externo de forma assíncrona, sem bloquear nem derrubar o INSERT se o destino cair.
Frontend
  • React 18 + TypeScript + Vite (SWC), Tailwind CSS com tokens HSL semânticos e componentes shadcn/ui sobre Radix.
  • 49 rotas com react-router-dom e 40 páginas carregadas sob demanda (lazy + Suspense), separando o peso do painel do peso da página pública.
  • TanStack Query para estado de servidor, react-hook-form + zod para formulários, Recharts e react-simple-maps para gráficos e mapa, jsPDF + html2canvas para relatórios.
  • PWA com vite-plugin-pwa: instalável, atualização automática e HTML servido pela rede (NetworkFirst) para que uma versão nova valha sem recarregamento forçado.
  • Acessibilidade e LGPD na interface: widget de acessibilidade, banner de consentimento e política de privacidade.
  • Máscara de dados em duas camadas: funções puras de mascaramento (nome, e-mail, telefone) e o Modo Privacidade, aplicado por atributo no <body> e regras de CSS.
Infraestrutura e deploy
  • Front publicado como estático por deploy contínuo a partir do branch principal, com fallback de rotas (_redirects) para deep links funcionarem.
  • Backend inteiramente gerenciado no Supabase: Postgres, Auth, Storage e Edge Functions.
  • Cloudflare Turnstile como CAPTCHA no cadastro e no login.
  • Redirecionamentos de domínio feitos na própria SPA, preservando a query string das UTMs, quando o tráfego público migrou para o site oficial.

06Segurança

8 ataques considerados, 8 defesas em produção.

ataquedefesa
Atalho pela API

Pular a interface e falar direto com o banco ou a API, com a chave pública na mão.

  • Robô cadastrando em massa direto pela API REST, pulando o CAPTCHA

    INSERT anônimo revogado na tabela de apoiadores; o único caminho público é uma Edge Function que valida o Turnstile no servidor

Contas e login

Força bruta, criação de contas indevidas, redefinição de senha e tomada de conta.

  • Força bruta de senha no login do painel ou do ativista

    Login por Edge Function com Turnstile e limite de 5 falhas por IP e 8 por e-mail em 2 minutos; resposta 429 com Retry-After; IP salvo só como hash

Escalada de privilégio

Quem tem algum acesso tentando ganhar mais: virar admin, ler o que não deve, manter acesso revogado.

  • Usuário comum lendo o CRM ou chamando RPCs do painel

    RLS com leitura só para admin, escrita só por funções SECURITY DEFINER, RPCs guardadas por is_admin() e sem EXECUTE para anon; papéis em tabela separada

Origem e requisições forjadas

CSRF, webhooks falsos, tokens reaproveitados, links assinados e redirecionamento aberto.

  • Forjar eventos no webhook do provedor de e-mail

    Assinatura Svix verificada antes de interpretar o corpo; demais webhooks exigem segredo próprio por integração

  • Usar o link de clique dos e-mails como open redirect para phishing

    Redirecionamento só para hosts de uma allowlist

  • Forjar um link de ativação de conta para outro usuário

    uid assinado com HMAC-SHA256 e assinatura recalculada no servidor antes de gerar o acesso

Adulteração e rastro

Mexer em contagens, apagar a base, editar o histórico ou negar o que foi autorizado.

  • Mandar colunas extras no cadastro para forjar indicação ou flags

    Registro montado a partir de uma whitelist de colunas na Edge Function

  • Apagar a base de apoiadores com uma conta comprometida

    Trigger por statement bloqueia DELETE de mais de 5 linhas; trigger BEFORE DELETE guarda snapshot completo e o autor em tabela que nenhum cliente escreve

Autenticação

  • O login de admin e de ativista não fala direto com o Auth: passa pela Edge Function login, que verifica o Turnstile e aplica limite de falhas por IP (5) e por e-mail (8) numa janela de 2 minutos, respondendo 429 com Retry-After. O IP é guardado só como hash SHA-256 na tabela login_attempts.
  • Política de senha (mínimo de 8 caracteres, uma maiúscula e um número) com checklist visual no front.
  • Ativação de conta por link com o uid assinado em HMAC-SHA256; a função de ativação recalcula a assinatura antes de gerar o acesso.

Autorização e RLS

  • RLS habilitada em todas as tabelas do schema público, com GRANT explícito para authenticated e service_role na mesma migration que cria a tabela.
  • Tabelas do CRM com leitura só para administradores e escrita só por funções SECURITY DEFINER; funções internas (normalização, mapeamento de origem, triggers) com EXECUTE revogado de anon e authenticated.
  • Funções do painel protegidas por is_admin(auth.uid()) e com EXECUTE revogado de anon.
  • Ativistas veem dados completos apenas dos apoiadores que eles mesmos indicaram; para o ranking público existe uma view que expõe só primeiro nome, código e contagem de indicações.

Superfície anônima

  • O INSERT anônimo direto na tabela de apoiadores foi revogado. O único caminho público de cadastro é a Edge Function submit-form, que valida o Turnstile, valida o mínimo no servidor e monta o registro a partir de uma whitelist de colunas, o que impede atribuir campos como código de indicação ou flags pela API.
  • Funções de consulta pública (existência de e-mail, código de indicação) devolvem só o mínimo necessário e não expõem nome nem papel.

Integrações

  • Webhook do Resend validado pela assinatura Svix antes de interpretar o corpo.
  • Webhooks de automação, chatbot e ingestão externa exigem um segredo próprio por integração no cabeçalho.
  • O redirecionamento de clique do tracking de e-mail só segue para hosts de uma allowlist, fechando o open redirect.

Proteção da base

  • Trigger BEFORE DELETE que grava um snapshot completo de cada apoiador apagado, com quem apagou, o papel, o endereço do cliente e a aplicação, numa tabela que só administradores leem e que nenhum cliente consegue escrever.
  • Trigger por statement que bloqueia qualquer DELETE de mais de 5 apoiadores de uma vez, a menos que a sessão ligue explicitamente uma flag administrativa.
  • Autoexclusão de conta desativada desde o incidente descrito abaixo, até a revisão do fluxo.

LGPD

  • Banner de consentimento, política de privacidade publicada, IPs armazenados como hash, máscara de dados sensíveis na tela e aviso de monitoramento nas telas de login.

07Desafios técnicos

Unificar a mesma pessoa vinda de muitas fontes

O telefone era a única chave presente em quase todos os formulários, mas chegava em formatos diferentes. Descobrimos que a função de "só dígitos" herdada da base removia também o caractere 0, o que faria telefones diferentes colidirem. A solução foi uma normalização nova com regexp_replace e corte do 55, um único ponto de ingestão no banco usado tanto pelos triggers de tempo real quanto pelo backfill, e a regra de que o perfil guarda a página de origem mais antiga enquanto cada cadastro posterior vira um evento da jornada e um registro de histórico de campo.

Um índice que quebrou o cadastro público

O backfill precisava casar apoiadores com perfis pelo telefone, e para isso foi criado um índice funcional sobre crm_digits(whatsapp). Na mesma migration, por boa prática, o EXECUTE dessa função tinha sido revogado de anon. Em produção, o formulário público passou a falhar com permission denied for function: o Postgres avalia a expressão do índice com o privilégio de quem faz o INSERT, não do dono da função. O hotfix devolveu EXECUTE só para essa função pura, documentou o motivo na migration e virou regra no guia do projeto.

Exclusão em massa e recuperação

Em abril de 2026 a base de apoiadores sofreu uma exclusão em massa. A resposta veio em camadas: primeiro a tabela de auditoria com snapshot completo por trigger, depois a restauração dos registros a partir desses snapshots (jsonb_populate_record com ON CONFLICT DO NOTHING), o trigger por statement que barra exclusões acima de 5 linhas e a desativação da função de autoexclusão de conta até nova revisão.

Fechar a porta dos fundos do cadastro

O CAPTCHA no front não protege nada se a tabela aceita INSERT anônimo pela API REST. O cadastro foi movido para uma Edge Function que valida o Turnstile e filtra colunas, e, com o front já usando esse caminho, o INSERT de anon foi revogado. O Turnstile foi feito para falhar aberto apenas enquanto o segredo não estivesse configurado, e fechado a partir daí.

08Resultados

  • Cerca de dez meses em produção, de dezembro de 2025 a setembro de 2026.
  • 1.847 commits, 221 migrations, 67 tabelas, 38 Edge Functions e 49 rotas.
  • Camada de CRM entregue numa sequência de 28 pull requests em cinco dias: perfil único, Lead Score manual e automático, funil por UTM, mapa geográfico e o endurecimento do cadastro público.
  • Quando o tráfego público migrou para o site oficial, o Alicerce continuou recebendo os cadastros do site novo por uma API autenticada, sem perder histórico nem pontuação.
1.847
Commits
como medimos

git rev-list --count HEAD

~10 meses
Período em produção
como medimos

git log: primeiro commit de produto em 2025-12-15, último em 2026-09-28

221
Migrations
como medimos

ls supabase/migrations | wc -l

67
Tabelas
como medimos

chaves de public.Tables em src/integrations/supabase/types.ts (tipos gerados)

177
Policies de RLS
como medimos

contagem de 'CREATE POLICY' em supabase/migrations/*.sql (declarações, inclui recriações)

38
Edge Functions
como medimos

ls supabase/functions | wc -l

49
Rotas
como medimos

contagem de <Route em src/App.tsx

~65 mil
Linhas de código
como medimos

linhas não vazias em arquivos versionados: TSX 34.434, TS 10.350 (inclui 6.987 das Edge Functions), SQL 13.300; tipos gerados excluídos (cloc indisponível)

09Linha do tempo

  1. dez 2025

    Primeira versão: landing pública e funil de cadastro gamificado

  2. jan 2026

    Área do Ativista, ranking de indicações e e-mail marketing; mês com 635 commits

  3. fev 2026

    PWA instalável e endurecimento de policies de RLS

  4. mar 2026

    Login passa por Edge Function com limite de tentativas

  5. abr 2026

    Auditoria de exclusões, restauração da base e trava contra DELETE em massa

  6. jul 2026

    CRM de mobilização em 28 PRs: perfil único, Lead Score, funil por UTM, mapa e Turnstile no cadastro e no login

  7. ago 2026

    Tráfego público migra para o site oficial; o CRM passa a receber os cadastros dele por API

  8. set 2026

    Último commit: redirecionamentos finais para o site oficial

10Stack

Frontend
  • React 18
  • TypeScript 5
  • Vite 5 (SWC)
  • Tailwind CSS 3
  • shadcn/ui (Radix)
  • TanStack Query 5
  • React Router 6
  • react-hook-form + zod
  • Recharts
  • react-simple-maps
  • vite-plugin-pwa
Backend
  • Supabase Edge Functions (Deno)
  • Supabase Auth
  • PL/pgSQL SECURITY DEFINER
  • PostgREST
  • Resend
  • n8n
  • Google Analytics 4 Data API
Dados
  • PostgreSQL (Supabase)
  • Row Level Security
  • pg_cron
  • pg_net
  • Supabase Storage
Infra
  • Hospedagem estática com deploy contínuo via GitHub
  • Supabase gerenciado
Segurança
  • Cloudflare Turnstile
  • Rate limiting de login no banco
  • HMAC-SHA256
  • Verificação de assinatura Svix
  • Auditoria por trigger
  • Allowlist de redirecionamento

11Ficha técnica

node@alicerce: ~/cases/alicerce
node@alicerce ─────────────
type
CRM de mobilização + PWA
stack
React 18 · Vite · TypeScript
db
Postgres · 67 tabelas · RLS
auth
Supabase Auth · login com rate limit
edge
38 Edge Functions (Deno)
anti-bot
Cloudflare Turnstile
modules
LPs · ativista · CRM · lead score · funil
status
concluído · 10 meses em produção
$ ls supabase/migrations | wc -l; ls supabase/functions | wc -l
221
38
$ psql -c "select crm_normalize_phone('+55 (51) 99999-0000');"
crm_normalize_phone
---------------------
51999990000
(1 row)
$ curl -s -X POST "$SUPABASE_URL/rest/v1/supporters" -H "apikey: $ANON_KEY" -d '{"nome_completo":"bot"}'
{"code":"42501","message":"permission denied for table supporters"}
$ for i in 1 2 3 4 5 6; do curl -s -o /dev/null -w '%{http_code} ' -X POST "$FN/login" -d @senha-errada.json; done
401 401 401 401 401 429
$ psql -c "delete from supporters where created_at < '2026-01-01';"
ERROR: Mass delete em public.supporters bloqueado: tentativa de apagar 1200 linhas em uma unica statement (limite: 5).
NODE

TECNOLOGIA E INTELIGÊNCIA POLÍTICA

© 2026 NODE. Todos os direitos reservados.