⚙️ Backend, WhatsApp e Agente IA

Comparação prática entre Convex (BaaS reativo, TypeScript first), Supabase (Postgres + auth + storage gerenciado) e Postgres puro (Neon, Railway). Cada um tem trade-off de produtividade, controle e custo.

Escolha errada vira refactor de 3 semanas no meio do projeto. Acertar no dia zero economiza tempo e dor — Convex pra MVP rápido, Supabase pra padrão SQL, Postgres puro pra escala extrema.

BaaS, reatividade, RLS, lock-in, custo por GB, latência de query, free tier limits.

Modelagem completa: organizations, users, contacts, conversations, messages, deals. Cada tabela com campos justificados pela operação real do produto, não pela vaidade técnica.

Schema bem feito é a coluna do produto. Esquema porco vira N+1 query, race condition e bug de dado fantasma. Aqui você sai com schema.ts pronto pra colar no Convex.

Entidades, atributos, normalização vs denormalização, soft delete, audit fields.

Como ligar tabelas (contact tem N messages, deal tem 1 contact), criar índices em campos de busca (telefone, status) e evitar full table scan quando o cliente cresce.

A maioria dos travamentos em produto SaaS vem de query sem índice. Saber onde indexar desde o dia zero evita que sua "página de conversas" fique 8s lenta com 5k registros.

Foreign key, índice composto, query plan, N+1, join lateral, paginação cursor.

Como o agente cria migrations expand-then-contract: adiciona coluna, popula, troca código, depois remove a antiga. Nunca derruba produção.

Cliente pagando R$ 2k/mês não aceita "ficou 10min fora". Migration zero-downtime é a diferença entre amador e profissional vendendo SaaS.

Expand/contract, backfill, rolling deploy, schema versioning, rollback.

Script seed.ts que popula o banco com dados realistas: nomes brasileiros, telefones BR, mensagens em português, deals em diferentes estágios. Perfeito pra dev e demo.

Demo pra cliente com banco vazio é tiro no pé. Seed bom é o que faz a UI parecer "cheia de gente usando" no primeiro screenshot pro prospect.

Faker, fixtures, idempotência de seed, ambiente dev vs demo, dados sintéticos LGPD-safe.

Backup automático no Convex/Supabase, snapshot manual antes de cada deploy crítico, política de retenção, plano de restore testado a cada 30 dias.

Perder dado de cliente é fim de relacionamento e processo trabalhista no horizonte. Backup só vale se você já testou restore — senão é placebo.

Point-in-time recovery, snapshot, retenção, RTO/RPO, drill de restore.

Evolution API é um wrapper open-source em volta do Baileys (cliente WhatsApp Web). Sem aprovação Meta, roda em VPS, conecta número pessoal ou business em minutos.

A oficial WhatsApp Cloud API leva 2–6 semanas pra aprovação BSP. Cliente brasileiro PME quer ver funcionando hoje. Evolution destrava esse "hoje" pelo trade-off certo.

Baileys, BSP, Cloud API oficial, ToS WhatsApp, sessão multi-device.

Comparação: rodar Evolution numa VPS Hetzner/Hostinger por R$ 30/mês vs usar provedor SaaS (UltraMsg, Z-API) que cobra R$ 100–300/mês mas tira a dor de operação.

Margem do seu SaaS depende disso. Self-host dá margem de 70%; cloud terceirizado fica em 30%. Saber operar destrava preço competitivo no BR.

VPS, uptime SLA, custo operacional, terceirização, build vs buy.

docker-compose.yml com Evolution + Postgres + Redis. Sobe num comando, expõe porta 8080 com painel web. Inclui variáveis de ambiente, volume persistente e healthcheck.

Docker abstrai 80% da operação. Mesmo comando local e em produção. É a diferença entre "funciona na minha máquina" e "funciona em qualquer cliente".

docker-compose, volumes, networks, env vars, healthcheck, restart policy.

Endpoint que gera QR code pra escanear com o WhatsApp do cliente. Sessão fica persistida no banco. Quando cair, reconecta sozinho — você não precisa pedir QR de novo.

Sessão que cai e exige QR toda vez é UX horrível pro cliente. Persistência e reconnect automático são o que faz o sistema "sumir" no bom sentido.

QR code pairing, multi-device, session persistence, reconnect backoff, logout remoto.

Endpoint /webhook/evolution no seu backend que recebe POST sempre que chega mensagem. Você valida assinatura, salva no banco, dispara o agente IA.

Webhook é o coração do produto. Errar aqui (idempotência, ordem, erro silencioso) é perder mensagem do cliente — pior bug que existe nesse domínio.

Webhook, idempotência, retry, assinatura HMAC, dead-letter queue.

Função sendMessage(to, payload) que abstrai o formato JSON da Evolution para texto, imagem (URL ou base64), áudio (mp3/ogg) e document (PDF). Inclui rate limit interno.

Mandar mensagem rápido demais derruba a sessão por flood. Saber respeitar limite e reaproveitar conexão é o que mantém o número online por meses sem cair.

Rate limit, throttle, base64 vs URL, mimetype, mensagens em massa, ban risk.

Estrutura do system prompt em 5 blocos: persona (quem é o agente), objetivo (qualificar lead pra reunião), ferramentas disponíveis, restrições (nunca prometer preço), formato de saída.

90% dos agentes ruins têm system prompt ruim. Estrutura clara é a diferença entre "vendedor virtual que fecha venda" e "chatbot esquisito que cliente xinga".

Persona, objetivo SMART, guardrails, formato JSON, exemplos few-shot.

Como passar para o agente as últimas N mensagens + perfil do contato + histórico resumido das conversas anteriores, sem ultrapassar 30k tokens nem queimar custo.

Mandar contexto cru a cada turno custa caro e degrada qualidade. Usar resumo + última janela + cache é o que torna agente economicamente viável.

Sliding window, sumarização hierárquica, prompt caching, tokens efetivos.

Schema de funções: createDeal, scheduleCall, updateContact, transferToHuman. Agente decide quando chamar, sistema executa, retorna resultado pro próximo turno.

Sem function calling, agente é só um chatbot bonito. Com, ele atua de fato no produto — cria registros, marca calendário, dispara follow-up. Aí vira valor pago.

Tool use, JSON schema, validação de argumentos, ciclo agentic, retry de tool falha.

Gatilhos automáticos: agente em loop sem progresso, cliente irritado (sentiment negativo), valor de deal acima de R$ X, palavra-chave "cancelar". Sistema avisa humano e congela bot.

Agente que insiste sozinho num cliente irritado vira reclamação no Reclame Aqui. Handoff fluido é o que protege a marca do seu cliente.

Detecção de loop, sentiment, escalation rules, UX de transição, contexto repassado.

Otimização: prompt caching pra economizar 90% em tokens repetidos, Haiku pra triagem barata + Sonnet pra resposta complexa, batch pra análise pós-fato (não tempo real).

Custo de IA é o que mata margem do SaaS. Diferença entre R$ 8 por cliente/mês e R$ 80 é só engenharia de custo. Aqui você aprende a fazer 90% de redução.

Prompt caching, batch API, model routing, cost per conversation, unit economics.

Log estruturado de cada turno: prompt, resposta, tools chamadas, custo, latência. Painel pra auditar o que o agente fez. Endpoint LGPD de "exportar/apagar dados deste contato".

Cliente vai perguntar "por que o bot disse isso?" Sem log, você fica sem resposta. LGPD obriga rastreabilidade — sem ela, multa de até 2% do faturamento.

Structured logging, traces, ANPD, direito do titular, retenção de dados.

Modelagem onde cada cliente do aluno tem organizationId próprio. Toda query filtra por org. Usuários só veem dados da sua organização — nunca da clínica concorrente.

Sem multi-tenant, você não vende SaaS, vende projeto. Multi-tenant bem feito é o que permite cobrar 10 clientes no mesmo backend e escalar margem.

Tenant ID, shared schema, isolated schema, pool pattern, silo pattern.

Setup do Clerk em 15 minutos: providers (email magic link, Google, GitHub), roles (owner, admin, agent), organizations nativas, webhook que cria registro no Convex.

Auth caseira é receita pra vazamento. Clerk resolve em horas o que levaria semanas — e libera você pra trabalhar no que diferencia o produto, não no login.

JWT, magic link, OAuth, roles, organizations, webhooks de auth.

Padrão de queries Convex onde cada função verifica orgId do usuário autenticado e filtra. Em Supabase, mesmo princípio com policies SQL. Bug aqui = vazamento.

Em SaaS multi-tenant, RLS quebrada vira manchete. É o controle final que protege o produto contra erro humano de query mal escrita.

RLS, policy, identity context, defense in depth, audit trail.

.env no .gitignore, secrets na Vercel/Convex Cloud por ambiente (dev/preview/prod), checklist de rotação a cada 90 dias, scan de leaks com gitleaks.

Secret no Git é a forma mais comum de invasão. 5 minutos seguindo o checklist evita boleto de R$ 50k da AWS por mineração de cripto.

Env vars, gitignore, gitleaks, vault, rotação, princípio do menor privilégio.

vercel deploy pro frontend, npx convex deploy pro backend reativo, integração GitHub que faz preview em cada PR. Em 3 comandos seu app está ao vivo.

Cliente paga por produto online, não por código no GitHub. Deploy fluido é o que transforma "fiz" em "vendi".

Build, edge function, preview deploy, environment, rollback de deploy.

Comprar domínio (Registro.br ou Cloudflare), apontar DNS pra Vercel, SSL emitido automático via Let's Encrypt. Subdomínio por cliente (cliente1.app.com.br).

Domínio próprio é o que separa MVP de produto vendável. Cliente sério não compra .vercel.app no link — ele compra app.suamarca.com.br.

DNS, CNAME, A record, Let's Encrypt, wildcard SSL, white-label.