Guias

Documentação técnica da plataforma flow-ai. Cada guia descreve um subsistema em detalhe — tipos TypeScript, fluxos de execução, integrações e comportamentos de borda.

Para uma visão geral rápida da arquitetura — serviços, packages, streams e caches — veja Arquitetura do sistema.

Fluxos de dados

Guia	Descrição
Jornada do usuário ponta-a-ponta	O caminho completo de uma mensagem por todos os serviços — dois cenários (flow→human com resume; agent→especialista→flow), diagramas de sequência com stream/cache por salto, tabela de responsabilidades e ciclo de abertura/fechamento de tickets.
Inbound completo	Da mensagem WhatsApp chegar na Meta até o engine executar o flow — validação HMAC, normalização, sessão, roteamento.
Outbound completo	Do engine publicar uma resposta até o WhatsApp receber — fan-out persist/send, internalId, status de entrega, Socket.io no desk.
Ciclo de vida da sessão	Criação, TTLs, transições de modo (flow/agent/human), encerramento e campos especializados da SessionState.
Coreografia entre serviços	Como os 7 serviços coreografam via Redis Streams — mapa produtor→consumidor das streams vivas, diagramas de sequência, padrão runStreamLoop, consumer groups, ACK/retry e graceful shutdown.

Domínio

Guia	Descrição
Router — entidade central	Agregado raiz do sistema — caches Redis, criptografia, warm-up, CRUD com sincronização imediata.
Ciclo de vida do contato	Criação, identidade multi-canal, multi-router, variáveis persistentes, WebChatIdentity e opt-in.
Catálogo de variáveis	RouterVariable e FlowVariable — escopo, criptografia AES-256-CBC, cache Redis, interpolação {{router.key}} / {{flow.key}} no engine.

Engine

Guia	Descrição
Execução do flow	Bootstrap do engine, fases de run, actions, conditions e publicação de mensagens.
Redirecionamentos	redirectToBot e returnToFlow — histórico de sessão, cross-router bloqueado e limite de hops.
Ação executeScript	Sandbox V8 Isolate, globals injetados, templates e tratamento de erros.
Ferramentas (Tools)	Mini-flows reutilizáveis de transformação de dados — blocos httpCall/executeScript/return, servidores de integração, cache Redis e action executeTool.

Agentes de IA

Guia	Descrição
Comunicação e ciclo de vida	Como o sistema roteia mensagens para agentes de IA, pré-processamento de mídia inbound (Whisper), o loop de execução do executor, multi-agente com agentChain, ferramentas disponíveis e retorno ao flow.

Integração externa

Guia	Descrição
API de gerenciamento de sessão	Endpoints para ler e manipular sessões ativas via HTTP — leitura de variáveis, merge de variáveis e redirect externo para blocos/flows.

Disparos ativos

Guia	Descrição
Disparo único de template	Como disparar um template aprovado pela Meta para um contato via API, com validação de opt-in e rastreamento de status de entrega.

Helpdesk

Guia	Descrição
Atendimento humano	Ciclo de vida do ticket, janela Meta 24h, expiração de sessão e controle do atendimento humano.
Pesquisa de satisfação	Bloco de CSAT: pergunta, captura da nota, contexto do flow e relatório de satisfação.
Tickets — modelo e ciclo de vida	Modelo Ticket: linhagem (previousTicketId), kind human/ai, enums de status/openReason/closeKind, tags, vínculo com a SessionState e sentimento.

Importação

Guia	Descrição
Importador de flows Blip	Requisitos de formato, padrões de script A/B/C/D/E, regras de conversão de actions, roteamento, variáveis e limpeza no cancelamento.

Segurança

Guia	Descrição
Autenticação e RBAC	JWT access + refresh tokens, hook authenticate, authorizePermission vs authorizeRoute, modelo Role/RoleRoute.
Criptografia e segredos	AES-256-CBC, RSA-2048, bcrypt — mapa completo do que é cifrado no Postgres, o que nunca sai via HTTP e a fronteira flow-ai-core/Redis.
Audit log	Registro imutável de ações — ações de auth, CRUD de entidades, retenção automática e endpoint de consulta com RBAC scoping.

Canais

Guia	Descrição
Multicanal — WhatsApp, WebChat e Instagram	Como os três canais convergem no mesmo pipeline stream:incoming e divergem nas bordas — contrato WhatsApp-shaped, roteamento por prefixo de sessionId, cobertura de conteúdo por canal e gaps conhecidos.
Canal WebChat	flow-ai-webchat-gateway, autenticação por sessionKey, WebChatIdentity, stream:outgoing-chat e entrega via Socket.io room.
Canal Instagram	flow-ai-ig-api: webhook IG (porta 4445, IG_VERIFY_TOKEN, sem Prisma), DMs → stream:incoming, saída via stream:outgoing-ig, e moderação de comentários (keyword → abertura/destino) com Private Reply vs resposta pública e a régua de gatilhos.
WhatsApp Flows declarativos	Diferença entre flows de bot e WhatsApp Flows Meta, ciclo draft→publish→sync, endpointConfig, criptografia RSA+AES-GCM e logs de webhook.

Referência

Guia	Descrição
Modelo de dados	Diagrama de entidades completo — todos os 77 modelos (+ 10 enums), relações, constraints e decisões de design do schema.

Infraestrutura

Guia	Descrição
Redis consumers	Conexões bloqueantes, consumer groups, mapa de streams e política de ACK/retry.
Logging	Pacote flow-ai-logger, níveis configuráveis via LOG_LEVEL e LOG_LEVEL_{SERVICE}, convenção pino e formato por ambiente.

---

Para agentes: veja o CLAUDE.md na raiz do app para saber quando e como adicionar novos guias.