Documento técnico — escopo, MVP e arquitetura
Documento vivo. Versão inicial, sujeito a revisão conforme aprendizado da execução.
Santa Cruz do Capibaribe é a principal cidade do Polo de Confecções do Agreste pernambucano, que reúne também Toritama e Caruaru. O polo concentra mais de 18 mil unidades produtivas formais e informais, fabricando roupas que abastecem comerciantes do Norte, Nordeste e Centro-Oeste do Brasil. A Feira da Sulanca e o Moda Center são pontos de venda físicos, mas a maior parte da negociação acontece via WhatsApp.
O comércio é majoritariamente B2B no atacado: faccionistas e fabricantes vendem para sacoleiros e revendedores que viajam até a região ou compram a distância. A relação é pessoal, baseada em confiança, e o canal de comunicação principal é o WhatsApp Business.
Pequeno faccionista/fabricante que vende no atacado, com as seguintes características:
- Faturamento mensal entre R$ 30 mil e R$ 300 mil
- Atendimento feito pelo próprio dono ou por uma a duas pessoas
- WhatsApp Business como canal principal de vendas
- Catálogo divulgado primariamente no Instagram e em status do WhatsApp
- Clientes finais são sacoleiros e revendedores de outros estados
- Ticket médio de pedido entre R$ 500 e R$ 5.000
O faccionista típico recebe centenas de mensagens por semana com perguntas que se repetem:
- "Tem pronta entrega da referência X?"
- "Qual o preço de atacado?"
- "Qual o mínimo do atacado?"
- "Qual a grade disponível?" (P ao GG, sortida, etc.)
- "Faz sob encomenda? Qual o prazo?"
- "Aceita Pix? Tem desconto?"
- "Manda o catálogo?"
Essas mensagens chegam em qualquer horário — incluindo madrugadas e domingos, quando sacoleiros de outros estados planejam viagens. O faccionista está produzindo, jantando ou dormindo, e responde horas depois. Quando responde, parte dos leads já comprou em outra loja.
Em segundas-feiras, o backlog acumulado do fim de semana toma a manhã inteira em vez de produção.
Estimativa conservadora: 20% a 40% das oportunidades são perdidas por demora.
Mensagens de áudio são intensivas no setor — especialmente vindas de clientes do interior do Nordeste, que falam mais rápido do que digitam. Um áudio típico contém múltiplas perguntas em uma só mensagem:
"Oi meu amor, tô querendo ver aqueles conjuntinhos que você postou ontem, tem P ao GG? é pra revender lá em Juazeiro, me manda o valor do atacado a partir de 30 peça, e me diz se tem pronta entrega porque eu vou aí na quarta"
Atender esse mercado bem exige tratamento de áudio como cidadão de primeira classe, não como recurso secundário.
- Comerciantes locais já adotaram o WhatsApp Business em massa
- Modelos de IA atingiram qualidade suficiente em português brasileiro, incluindo transcrição de áudio com sotaque regional
- WhatsApp Cloud API oficial da Meta tornou-se acessível e estável
- Concorrentes nacionais focam em grandes redes e em chatbots genéricos — há espaço para um produto vertical, especializado no setor de confecções
Estimando que 30% das unidades produtivas do polo se enquadram no perfil de cliente ideal e que 10% poderiam ser convertidas em três anos, o mercado endereçável de partida é de 500 a 600 clientes pagantes apenas na região. Replicação para outros polos têxteis brasileiros (Brás, Divinópolis, Nova Friburgo, Goiânia) multiplica esse número.
O MVP é o produto mínimo que faz o faccionista olhar para o sistema funcionando e dizer "isso me ajuda de verdade". Tudo que não contribui para esse momento fica de fora.
Atendimento automático no WhatsApp
- Conexão com o WhatsApp Business do faccionista via WhatsApp Cloud API oficial
- Resposta automática a perguntas frequentes baseada no catálogo cadastrado
- Envio de fotos de peças quando solicitado
- Envio de catálogo em PDF quando solicitado
- Personalidade configurável (nome do bot, tom de voz)
- Horário de atuação configurável (24 horas ou faixas específicas)
Tratamento de áudio
- Recebimento e armazenamento seguro de áudios dos clientes
- Transcrição automática via Whisper API
- Extração estruturada de múltiplas intenções por áudio
- Resposta em texto com tratamento de cada pergunta identificada
- Fallback educado quando confiança da transcrição é baixa
- Áudio original e transcrição visíveis no painel do faccionista
Gestão de catálogo
- Importação automática a partir do Instagram do faccionista (fotos, legendas, preços)
- Cadastro manual complementar de peças
- Campos por peça: nome, referência, fotos, preço atacado, mínimo de atacado, grade, status (pronta entrega ou encomenda), prazo se encomenda, descrição
- Edição rápida no painel mobile
Captura e qualificação de leads
- Identificação do contato (nome, telefone)
- Extração de informações do cliente durante a conversa (cidade, perfil de compra, urgência)
- Visualização de leads e conversas no painel
Escalada para humano
- Detecção automática de momentos que exigem humano (negociação, pedido grande, cliente insatisfeito, dúvida fora do catálogo)
- Notificação no WhatsApp pessoal do faccionista com resumo do contexto
- Possibilidade de o faccionista assumir conversa a qualquer momento
Painel web do faccionista
- Mobile-first
- Visualização de todas as conversas em andamento
- Histórico completo de mensagens (texto, áudio, transcrição)
- Cadastro e edição de catálogo
- Configurações do bot
Onboarding rápido
- Cadastro inicial via conversa no WhatsApp da empresa, não via formulário
- Importação automática de catálogo do Instagram
- Conexão com WhatsApp do cliente via Cloud API com suporte humano direto
- Tempo objetivo: pagamento até primeira resposta automatizada em menos de 30 minutos
Deliberadamente excluídas para preservar foco:
- Geração automática de pedido com link de pagamento Pix
- Resposta em áudio com voz clonada (síntese de voz)
- Dashboard com métricas avançadas e relatórios
- Disparo em massa, campanhas e reengajamento automático
- Múltiplos atendentes humanos por conta
- Integração com ERPs e plataformas de e-commerce
- App mobile nativo (o painel web mobile-first basta)
- White-label para revendedores
- Detecção de emoção em áudio
- Conversas em tempo real com áudio streaming
Cada um desses itens entra como feature subsequente, conforme demanda real e maturidade do produto.
Assinatura mensal por loja.
- Plano básico: R$ 197/mês — atendimento em texto, transcrição de áudio, catálogo, painel
- Plano premium (fase 2): R$ 397/mês — inclui resposta em áudio com voz clonada e funcionalidades avançadas
- Sem fidelidade, cancelamento livre
- 15 dias gratuitos para teste
- Pagamento via Pix recorrente (Asaas/Iugu) ou cartão de crédito
| Métrica | Meta nos primeiros 6 meses |
|---|---|
| Tempo do clique no link até bot ativado | Menor que 30 minutos para 50% dos novos clientes |
| Percentual de conversas resolvidas pelo bot sem intervenção | Acima de 60% |
| Tempo médio até primeira resposta ao cliente final | Abaixo de 30 segundos para texto, 60 segundos para áudio |
| Retenção do cliente no segundo mês | Acima de 70% |
| Clientes pagantes ao fim do mês 6 | 20+ |
- Boring tech vence hype. Stack maduro, documentado, fácil de debugar.
- Monolito modular, não microserviços. Único repositório, único deploy, workers separados consumindo do mesmo código.
- Fila é a espinha dorsal. Toda mensagem entra numa fila antes de processar. Resiliência, controle de rate limit, observabilidade.
- Multi-tenant desde o dia 1. Toda tabela tem
tenant_id. RLS no banco como segunda camada de defesa. - Áudio é cidadão de primeira classe. Pipeline completo desenhado para áudio, não adaptado depois.
O sistema é organizado em seis camadas lógicas:
- Mundo externo: clientes finais no WhatsApp, faccionistas, APIs de IA (LLM e Whisper), provedor de pagamento
- Borda HTTP: webhooks e API REST do painel
- Filas: Redis com BullMQ, segregadas por tipo de trabalho
- Workers: processos separados rodando do mesmo código, consumindo de filas diferentes
- Persistência: Postgres para dados, Redis para cache, R2 para mídia
- Frontend: painel Next.js do faccionista
| Camada | Escolha | Justificativa |
|---|---|---|
| Linguagem backend | Node.js (TypeScript) | Ecossistema de WhatsApp em JS, compartilha tipos com frontend |
| Framework HTTP | Fastify ou NestJS | Performance e estrutura para multi-tenant |
| Filas | BullMQ + Redis | Padrão de mercado em Node, simples e robusto |
| Banco principal | Postgres + pgvector | Relacional + busca semântica num banco só |
| ORM | Prisma ou Drizzle | Migrations versionadas, tipagem forte |
| Storage de mídia | Cloudflare R2 | Egress gratuito (crítico para fotos/áudios) |
| Frontend | Next.js + Tailwind | Velocidade de desenvolvimento, deploy fácil |
| WhatsApp Cloud API (Meta) | Oficial, estável, sem risco de banimento | |
| Transcrição | OpenAI Whisper API | Melhor custo-benefício em PT-BR com sotaque |
| LLM | Claude (Haiku/Sonnet) ou GPT-4o-mini | Modelo menor por padrão, maior em casos complexos |
| Hospedagem backend | Railway (MVP) → Fly.io (escala) | Simples no início, controle depois |
| Hospedagem frontend | Vercel | Padrão para Next.js |
| Logs | Logtail ou Axiom | Tier gratuito generoso, JSON nativo |
| Erros | Sentry | Alertas em tempo real |
| Pagamento | Asaas ou Iugu | Pix recorrente nativo brasileiro |
Apenas três endpoints públicos no MVP. Cada um com responsabilidade única e resposta rápida.
POST /webhooks/whatsapp/:tenantId — recebe eventos do WhatsApp Cloud API.
Responsabilidades estritas:
- Validar assinatura HMAC do Meta
- Identificar o tenant a partir do número de destino
- Gravar evento bruto em
webhook_eventspara auditoria - Enfileirar na fila apropriada (texto ou áudio)
- Responder 200 em menos de 500ms
Não faz: chamada a LLM, download de mídia, qualquer operação cara. Webhook que demora gera retentativa do Meta e duplicação.
POST /webhooks/billing — recebe eventos do provedor de pagamento.
- Idempotente (mesma notificação processada múltiplas vezes não duplica efeito)
- Atualiza status da assinatura
- Dispara onboarding ou suspende serviço
/api/* — API REST consumida pelo painel.
- Autenticação JWT
- CRUD de catálogo
- Listagem de conversas e mensagens
- Configurações do bot
- Métricas básicas
Quatro filas no mesmo Redis, segregadas estrategicamente.
Fila de texto
- Mensagens de texto puras
- Rápida (3 a 8 segundos por job)
- Concorrência alta, prioridade alta
Fila de áudio
- Áudios que precisam download, storage e transcrição
- Mais lenta (5 a 15 segundos por job), mais cara
- Rate limit consciente do Whisper
- Concorrência menor, retry mais paciente
Fila de envio
- Única fila que fala com o WhatsApp para enviar
- Centraliza throttling e rate limits do Meta
- Implementa prioridades (alerta ao faccionista passa na frente)
- Ponto único para regras de horário ("não envia entre 23h e 6h")
Fila de tarefas gerais
- Imports de catálogo do Instagram
- Geração de embeddings em massa
- Limpezas e jobs agendados (cron)
- Reprocessamento
Detalhe importante: uso de delayed jobs para agrupamento de mensagens. Cliente que envia 5 mensagens em 30 segundos não recebe 5 respostas — o worker espera 8 a 10 segundos depois da última, junta tudo, responde uma vez. Resultado mais natural e economia de tokens.
Mesma base de código, processos separados consumindo de filas diferentes. Em Railway/Fly cada worker é um serviço apontando para o mesmo repositório com comando de start diferente (npm run worker:text, npm run worker:audio, etc.).
Worker de conversa (cérebro do bot)
Recebe job com tenantId e conversationId. Fluxo:
- Verifica agrupamento — se chegou outra mensagem nos últimos 8 segundos, requeue com delay
- Busca histórico das últimas 15 mensagens da conversa
- Gera embedding da pergunta atual
- Busca vetorial em
product_embeddingsdo tenant para top 5 produtos relevantes - Monta prompt: instruções base + configurações do tenant + produtos relevantes + histórico + mensagem atual
- Chama LLM com tools definidas
- Executa as tool calls retornadas (cada tool enfileira jobs na fila de envio)
Tools disponíveis ao LLM:
enviar_texto(conteudo)enviar_foto_produto(productId)enviar_catalogo_pdf()escalar_humano(motivo, resumo)pedir_clarificacao(motivo)registrar_lead_info(campo, valor)
Worker de áudio
Fluxo:
- Baixa OGG do endpoint de mídia do Meta (URL temporária)
- Salva no R2 sob
media-audio/{tenantId}/{conversationId}/{messageId}.ogg - Atualiza a
messagecomaudio_url - Envia arquivo para Whisper API
- Persiste transcrição na message
- Verifica confiança — se baixa, marca para fallback de pedido de clarificação
- Enfileira na fila de texto referenciando a mesma
conversationId
Após transcrição, áudio vira indistinguível de texto no fluxo, simplificando a lógica downstream.
Worker de envio
- Consome fila de envio respeitando rate limits configuráveis por tenant
- Retry exponencial em falhas
- Circuit breaker se número específico apresenta problema
- Atualiza status da mensagem (sent, delivered, read) via webhook de status do Meta
Worker de tarefas gerais
Cron diário:
- Deletar áudios com mais de 90 dias (LGPD)
- Gerar relatório de uso por tenant
- Verificar saúde de números do WhatsApp
- Backup adicional do banco para R2
Sob demanda:
- Importar catálogo do Instagram
- Recalcular embeddings após alteração de catálogo
- Reprocessar mensagens com falha
Schema organizado por domínio. Toda tabela exceto globais carrega tenant_id.
Tenancy e usuários
| Tabela | Função |
|---|---|
tenants |
Loja do faccionista, configurações do bot |
users |
Faccionista e auxiliares |
subscriptions |
Status do pagamento, plano contratado |
Catálogo
| Tabela | Função |
|---|---|
products |
Peça (nome, referência, preço atacado, mínimo, descrição, status) |
product_images |
Múltiplas fotos por peça |
product_embeddings |
Vetor da descrição (vector(1536)) para RAG |
Conversas e mensagens
| Tabela | Função |
|---|---|
whatsapp_accounts |
Mapeia número do WhatsApp para tenant |
contacts |
Cliente final que escreveu (telefone, nome, cidade, etc.) |
conversations |
Uma por contato + tenant; status: ativa, escalada, resolvida |
messages |
Texto e mídia; direction in/out; sender cliente/bot/humano; audio_url; transcription |
webhook_events |
Log bruto para debug |
Operação do bot
| Tabela | Função |
|---|---|
bot_configs |
Instruções customizadas por tenant, FAQs, tom de voz |
escalations |
Quando bot transferiu para humano e por quê |
events |
Auditoria geral, base para análise futura |
Regras de ouro do schema
- Toda tabela com
tenant_idindexado, exceto globais - Row Level Security (RLS) ativada no Postgres como segunda camada de defesa
- Soft delete em todas as tabelas com coluna
deleted_at - Timestamps
created_ateupdated_atem tudo - IDs como UUID v7 (ordenados temporalmente, melhores para índice)
Cloudflare R2 escolhido por egress gratuito — crítico quando fotos de produtos são baixadas e enviadas constantemente.
Estrutura de buckets
media-products/{tenantId}/{productId}/{imageId}.jpg
media-audio/{tenantId}/{conversationId}/{messageId}.ogg
media-temp/{anyId}.{ext}
Regras
- URLs assinadas com expiração de 1 hora para servir ao painel
- Buckets nunca públicos
- TTL automático em
media-temp - Áudios encriptados em repouso
Pior caso (áudio é mais lento que texto) — mostra todas as peças trabalhando juntas.
-
Recebimento (200ms) — Cliente envia áudio de 50s. Meta entrega POST em
/webhooks/whatsapp/:tenantId. Webhook valida HMAC, identifica tenant, identifica/cria contact, encontra/cria conversation, grava message em estadoreceivedcom referência ao anexo, enfileira na fila de áudio. Responde 200. -
Processamento de áudio (5 a 10s) — Worker de áudio pega o job, faz GET no endpoint de mídia do Meta, salva OGG no R2, atualiza message com audio_url, envia para Whisper. Whisper retorna transcrição em 3 a 8s. Worker grava transcrição na message, enfileira na fila de texto.
-
Geração de resposta (3 a 6s) — Worker de conversa pega o job. Verifica agrupamento (se chegou outra mensagem nos últimos 8s, espera). Busca histórico, gera embedding, busca produtos relevantes via pgvector, monta prompt, chama LLM com tools. LLM retorna sequência de tool calls (ex:
enviar_texto,enviar_foto_produto,enviar_texto). Worker enfileira cada call na fila de envio. -
Envio (1 a 3s) — Worker de envio pega cada job respeitando rate limit. Envia via Meta API, recebe ID, atualiza message com whatsapp_message_id e status
sent. Quando Meta confirma entrega via webhook de status, atualiza paradeliverede depoisread.
Tempo total recebimento → primeira resposta visível: 8 a 15 segundos para áudio, 4 a 8 segundos para texto.
O ponto que merece atenção máxima — vazar dado entre clientes é fim do negócio.
Camada 1 — aplicação: todo acesso a dados passa por repositório que recebe tenant_id do contexto da requisição (extraído do JWT) e injeta no WHERE. Padrão obrigatório, nunca queries diretas sem tenant.
Camada 2 — banco: RLS configurado no Postgres. Mesmo que a aplicação esqueça, o banco bloqueia.
Camada 3 — testes: testes específicos verificando isolamento entre tenants em todos os endpoints. Tenant A nunca consegue ler dados de tenant B por nenhum caminho.
Para workers, tenant_id viaja no payload do job, e o primeiro código de todo worker é setar o contexto. Logs sempre incluem.
Logs estruturados em JSON com tenant_id, conversation_id, message_id em toda linha. Vão para Logtail ou Axiom.
Métricas mínimas no dashboard
- Mensagens recebidas/enviadas por minuto
- Latência p50/p95/p99 de cada worker
- Tamanho de cada fila
- Taxa de erro por tenant
- Custo de API por tenant
Alertas no Telegram ou WhatsApp pessoal do fundador
- Worker travado por mais de 5 minutos
- Fila com mais de 100 jobs pendentes
- Taxa de erro acima de 5% em janela de 5 minutos
- Bot de tenant específico mudo por mais de 30 minutos
Sentry para captura de exceções não tratadas.
- Todos segredos em variáveis de ambiente, nunca commitados
- HMAC validado em todos os webhooks
- JWT com expiração curta no painel
- Áudios encriptados em repouso
- Política de retenção: áudios deletados após 90 dias, transcrições mantidas
- Termos de uso explícitos sobre tratamento de dados de clientes finais
- Faccionista pode configurar retenção mais curta se quiser
- DPO designado e canal de contato para titulares
Por cliente ativo, assumindo 200 mensagens/dia (50% áudio):
| Item | Faixa mensal por cliente |
|---|---|
| WhatsApp Cloud API | R$ 50 a 100 |
| LLM (texto) | R$ 120 a 300 |
| Whisper (áudio) | R$ 30 a 60 |
| Storage R2 | R$ 5 a 15 |
| Hospedagem rateada | R$ 15 a 40 |
| Total variável | R$ 220 a 515 |
Implicações
- Plano básico R$ 197 aperta margem em clientes muito ativos — necessidade do plano premium R$ 397
- Otimização agressiva é prioridade: cache de respostas idênticas, modelo menor por padrão, agrupamento de mensagens
- Considerar limites no plano básico (X mensagens incluídas, excedente cobrado)
- Monitoramento de custo por tenant desde o dia 1
MVP (até 30 clientes)
- Backend e workers no Railway (serviços separados, mesmo repositório)
- Postgres gerenciado no Railway ou Neon
- Redis no Upstash (tier gratuito generoso)
- Frontend Next.js na Vercel
- Storage no Cloudflare R2
Escala (50+ clientes)
- Migração para Fly.io ou Hetzner com mais controle
- Postgres em provedor dedicado (Neon, Crunchy)
- Redis dedicado
Pipeline de deploy
- Git push em main faz deploy automático
- Migrations rodam automaticamente no deploy
- Rollback via revert do commit
- Backups diários do Postgres para R2 (redundância)
Semana 1 — Esqueleto vivo
- Monorepo Next.js + Fastify + Postgres + Redis com Docker Compose
- Webhook recebe e enfileira mensagens de teste
- Worker de teste consome e grava no banco
- Deploy no Railway funcionando
Semana 2 — WhatsApp em produção
- Conta no WhatsApp Business Platform aprovada
- Integração completa com Cloud API: receber e enviar texto
- Multi-tenancy no banco com RLS configurado e testado
Semana 3 — Cérebro do bot
- Worker de conversa com Claude/GPT respondendo
- Definição das tools do LLM
- Painel mínimo do faccionista para visualizar conversas
Semana 4 — Catálogo e RAG
- Cadastro manual de produtos no painel
- Geração de embeddings com pgvector
- RAG funcional: bot responde com base no catálogo do tenant
Semana 5 — Áudio
- Download de áudio via API do Meta
- Integração com Whisper
- Pipeline completo: áudio → transcrição → texto → resposta
- Painel mostra áudio + transcrição lado a lado
Semana 6 — Onboarding e cobrança
- Importação de catálogo do Instagram
- Conexão de WhatsApp via Cloud API com suporte humano
- Integração com Asaas (assinatura recorrente Pix/cartão)
- Primeira venda real possível
Semanas 7 e 8 — Polimento
- Observabilidade decente (logs, métricas, alertas)
- Tratamento de casos extremos (áudio vazio, mensagens duplicadas, falhas de LLM)
- Primeiros betas em produção com acompanhamento próximo
- Documentação interna para suporte
Duas verificações em paralelo na semana 0:
Validação técnica do Whisper
- Coletar 10 áudios reais de conversas de WhatsApp do setor (com permissão)
- Passar pela API do Whisper
- Avaliar acurácia em palavras críticas (referências, quantidades, cidades)
- Critério: acima de 90% nas palavras importantes
Validação burocrática do WhatsApp
- Criar conta no WhatsApp Business Platform
- Iniciar processo de verificação do número
- Mandar primeiro "hello world" via curl
- Identificar travas antes que entrem no caminho crítico
Independente do código, executar nas semanas 1 a 4:
- 15 entrevistas presenciais com pequenos faccionistas
- Mapeamento de perguntas frequentes (vira dataset)
- Identificação de 3 a 5 betas comprometidos
- Documentação de objeções e dúvidas para o pitch
| Termo | Significado |
|---|---|
| Faccionista | Quem fabrica peças (em costura própria ou facção menor) |
| Sacoleiro | Comprador que viaja para revender em sua cidade |
| Pronta entrega | Peça em estoque para envio imediato |
| Encomenda | Peça produzida sob demanda, com prazo |
| Grade | Conjunto de tamanhos disponíveis (P ao GG, sortida) |
| Sortida | Mix de tamanhos vendido em conjunto |
| Atacado | Venda em quantidade com preço diferenciado |
| Mínimo | Quantidade mínima para preço de atacado |
| Referência | Código ou nome da peça no catálogo |
| Malhão | Tecido de malha grossa, comum em conjuntos |
| Polo de Confecções do Agreste | Conjunto Santa Cruz + Toritama + Caruaru |
| Risco | Mitigação |
|---|---|
| Banimento de número WhatsApp | WhatsApp Cloud API oficial desde o dia 1, política rígida sem disparos sem opt-in |
| Rejeição cultural ao bot | Personalidade configurável, escalada rápida para humano, fase 2 com voz clonada |
| Concorrência genérica nacional | Verticalização: vocabulário do setor, onboarding em minutos, atendimento local |
| Qualidade insuficiente de transcrição | Validação empírica antes do código, fine-tuning se necessário, fallback para texto |
| Custo de IA escalando descontroladamente | Monitoramento por tenant desde dia 1, cache, modelo menor por padrão, limites no plano |
| Vazamento de dados entre tenants | Defesa em 3 camadas: aplicação, RLS no banco, testes de isolamento |
- Nome do produto e domínio
- Nome do bot padrão (se neutro ou personalizado por tenant)
- Política exata de retenção de dados
- Estrutura jurídica da empresa
- Termos de uso e política de privacidade
- WhatsApp Cloud API — documentação oficial Meta for Developers
- OpenAI Whisper API — documentação
- pgvector — extensão Postgres para busca vetorial
- BullMQ — documentação de filas
- LGPD — Lei nº 13.709/2018
Documento mantido pelo fundador. Atualizações mensais conforme execução.