Como construimos o FluKAI: arquitetura de uma secretaria IA para clinicas no WhatsApp

O FluKAI nasceu de uma frustração real: meu amigo Gustavo, que hoje e o diretor financeiro do produto, me contou que a clinica da familia perdia pacientes toda semana porque as mensagens do WhatsApp demoravam horas para serem respondidas. A secretaria era sobrecarregada, os pacientes desistiam, e os medicos ficavam com agenda vazia ao lado de agenda cheia — tudo por falta de triagem eficiente.

Em 2024, decidimos construir a solucao. Hoje, um ano e meio depois, o FluKAI processa mais de 1.200 consultas por mes em clinicas brasileiras. Aqui esta o que aprendemos construindo isso do zero.

As decisoes de stack

NestJS (Node.js/TypeScript) como backend: escolha por familiaridade do time, ecossistema maduro e bom suporte para modulos independentes — essencial quando voce tem 35+ modulos 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 clinicas atualiza conversas em tempo real sem polling.

Anthropic Claude como LLM: testamos GPT-4 e Claude lado a lado por tres semanas. Claude ganhou em seguir instrucoes complexas sem alucinar, especialmente em contextos medicos onde precisao e critica.

Meta WhatsApp Cloud API v21: a unica opcao viavel para escala no Brasil. A API Baileys (unofficial) e tentadora pelo custo zero, mas voce nao quer seu produto dependendo de uma API nao-oficial que pode ser bloqueada a qualquer momento.

Redis para locks de atendimento humano e deduplicacao: quando uma secretaria assume a conversa, o bot precisa sair do caminho imediatamente. Um lock distribuido no Redis garante isso sem condicao de corrida entre o bot e o humano.

O pipeline de 13 etapas

Cada mensagem que entra no FluKAI passa por 13 verificacoes de seguranca antes de chegar a IA. Nao e burocracia — e necessidade:

1. Verificacao HMAC-SHA256 do webhook da Meta
2. Resolucao da organizacao via numero 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 + redacao de PII antes de armazenar
6. Verificacao de lock de atendimento humano (Redis)
7. Verificacao de AI mode ativo
8. Verificacao de horario comercial
9. Verificacao de quota mensal de conversas IA
10. Verificacao de pausa manual da IA
11. Deteccao de bandeira vermelha de emergencia medica
12. Deteccao de injecao de prompt
13. Redacao de PII antes de enviar ao Claude

So depois disso a mensagem chega ao Dify (nossa camada de orquestracao de agentes) e ao Claude. Esse pipeline levou tres meses para ficar robusto em producao.

A arquitetura de multi-tenancy

O FluKAI atende multiplas clinicas simultaneamente. Cada clinica tem:

• Seu proprio agente de IA com system prompt customizado (nome, especialidade, tom)
• Seus proprios templates de WhatsApp aprovados pela Meta
• Sua propria cota mensal de conversas (baseada no plano contratado)
• Isolamento total de dados por org_id (sem Row Level Security no DB — seguranca na camada de aplicacao)

O maior erro que cometemos

Nao planejamos para o volume de webhooks. A Meta pode mandar o mesmo evento multiplas vezes. Sem deduplicacao robusta, o mesmo agendamento era criado duas ou tres vezes. Levamos dois meses para resolver completamente — e so resolvemos quando implementamos idempotency keys em todos os endpoints criticos.

Se voce esta construindo qualquer sistema que recebe webhooks de terceiros: implemente deduplicacao no dia um. Nao 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 experiencia do paciente. Hoje rodamos tudo com @nestjs/schedule e crons, o que funciona, mas uma fila seria mais elegante para escala.

Se voce 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.