Como construimos o FluKAI: arquitetura de uma secretária IA para clínicas no WhatsApp

O FluKAI nasceu de uma frustração real: meu amigo Gustavo, que hoje é o diretor financeiro do produto, me contou que a clínica da família perdia pacientes toda semana porque as mensagens do WhatsApp demoravam horas para serem respondidas. A secretária era sobrecarregada, os pacientes desistiam, e os médicos ficavam com agenda vazia ao lado de agenda cheia — tudo por falta de triagem eficiente.

Em 2024, decidimos construir a solução. Hoje, um ano e meio depois, o FluKAI atende pacientes de clínicas brasileiras no WhatsApp 24 horas por dia, com tempo mediano de resposta de 21 segundos e cobertura integral dos turnos noturnos e de fim de semana — a janela em que uma equipe humana simplesmente não está disponível. Aqui está o que aprendemos construindo isso do zero.

As decisões de stack

NestJS (Node.js/TypeScript) como backend: escolha por familiaridade do time, ecossistema maduro e bom suporte para módulos independentes — essencial quando você tem 35+ módulos como o FluKAI.

Supabase como banco de dados e auth: descartamos TypeORM desde o inicio (sem ORM, acesso direto via supabase-js). A vantagem do Supabase foi o Realtime nativo — o console web das clínicas atualiza conversas em tempo real sem polling.

Anthropic Claude como LLM: testamos GPT-4 e Claude lado a lado por três semanas. Claude ganhou em seguir instrucoes complexas sem alucinar, especialmente em contextos médicos onde precisao e critica.

Meta WhatsApp Cloud API v21: a única opção viavel para escala no Brasil. A API Baileys (unofficial) e tentadora pelo custo zero, mas você não quer seu produto dependendo de uma API não-oficial que pode ser bloqueada a qualquer momento.

Redis para locks de atendimento humano e deduplicacao: quando uma secretária assume a conversa, o bot precisa sair do caminho imediatamente. Um lock distribuido no Redis garante isso sem condição de corrida entre o bot é o humano.

O pipeline de 13 etapas

Cada mensagem que entra no FluKAI passa por 13 verificacoes de segurança antes de chegar a IA. Não é burocracia — e necessidade:

1. Verificacao HMAC-SHA256 do webhook da Meta
2. Resolucao da organização via número de telefone
3. Mark-as-read assincrono (UX: o paciente ve que foi lido)
4. Upsert do cliente/conversa/kanban card
5. Download de midia + redação de PII antes de armazenar
6. Verificacao de lock de atendimento humano (Redis)
7. Verificacao de AI mode ativo
8. Verificacao de horário comercial
9. Verificacao de quota mensal de conversas IA
10. Verificacao de pausa manual da IA
11. Detecção de bandeira vermelha de emergência médica
12. Detecção de injecao de prompt
13. Redação de PII antes de enviar ao Claude

Só depois disso a mensagem chega ao Dify (nossa camada de orquestracao de agentes) e ao Claude. Esse pipeline levou três meses para ficar robusto em produção.

A arquitetura de multi-tenancy

O FluKAI atende múltiplas clínicas simultaneamente. Cada clínica tem:

• Seu próprio agente de IA com system prompt customizado (nome, especialidade, tom)
• Seus próprios templates de WhatsApp aprovados pela Meta
• Sua própria cota mensal de conversas (baseada no plano contratado)
• Isolamento total de dados por org_id (sem Row Level Security no DB — segurança na camada de aplicação)

O maior erro que cometemos

Não planejamos para o volume de webhooks. A Meta pode mandar o mesmo evento múltiplas vezes. Sem deduplicacao robusta, o mesmo agendamento era criado duas ou três vezes. Levamos dois meses para resolver completamente — e só resolvemos quando implementamos idempotency keys em todos os endpoints criticos.

Se você esta construindo qualquer sistema que recebe webhooks de terceiros: implemente deduplicacao no dia um. Não no dia sessenta.

O que fariamos diferente

Comecar com uma fila de mensagens (BullMQ ou similar) desde o inicio, em vez de processar tudo sincrono. Com volume alto, o processamento sincrono cria picos de latencia que impactam a experiência do paciente. Hoje rodamos tudo com @nestjs/schedule e crons, o que funciona, mas uma fila seria mais elegante para escala.

Se você esta construindo um produto similar, posso te contar muito mais em detalhes. O FluKAI continua evoluindo — e estamos sempre abertos a discutir arquitetura com outros builders.