Arquitetura da plataforma¶

Visão geral¶

O GoGenetic Agente Digital recebe mensagens do WhatsApp, identifica a intenção do cliente, qualifica o serviço, coleta cadastro e entrega a conversa a uma pessoa. O estado e os dados pertencem à aplicação; os modelos de linguagem propõem ações estruturadas. O sistema decide se essas ações são válidas, grava a sessão e executa integrações.

Esta referência descreve o working tree da branch fix/ajustes, commit base 175a0bd986675a75ef760349b123595bf9fe714d, auditado em 14/09/2026. Na auditoria inicial não havia código rastreado modificado; existia o arquivo não rastreado docs/Integracao-Agente-GoGenetic.pdf, preservado. Configuração em produção, credenciais e respostas de providers não foram verificadas por esta documentação.

flowchart LR
    WA[WhatsApp Cloud API] --> WH[Webhook Lambda]
    WH --> DB[(DynamoDB single-table)]
    WH --> Q[SQS FIFO por telefone]
    Q --> OR[Orchestrator Lambda]
    OR --> UC[process_message]
    UC --> INV[AgentInvokerImpl]
    INV --> AI[OpenAI Responses API]
    INV --> KB[Packages e prompts versionados]
    KB --> DB
    UC --> DB
    UC --> EG[eGestor: contato]
    UC --> CRM[CRM: contato]
    OR --> WA
    DB --> SYNC[Worker crm_sync agendado]
    SYNC --> CRM
    UC --> H[Notificador de handoff]
    H --> OP[Operadores]
    OP --> UI[Painel atendimento]
    UI --> DB
    UI --> WA

O diagrama separa duas escritas no CRM: o contato pode ser atualizado durante a confirmação; o negócio comercial é projetado pelo worker assíncrono após persistência da sessão. O worker usa registros duráveis no DynamoDB, e não a fila SQS de mensagens.

Camadas e consumidores¶

Camada	Localização real	Responsabilidade e dependências
Entrada HTTP	`src/webhook_handler/app.py`	Verificação Meta, assinatura, tradução do payload, deduplicação e classificação entre comandos, atendimento humano, mídia e texto do bot
Transporte assíncrono	`src/orchestrator/app.py`	Receber wake-up FIFO, drenar receipts, construir `TurnGuard`, entregar/reentregar resposta e informar falhas parciais
Aplicação	`src/core/application/`	Fluxo da sessão, dispatcher, confirmação, contexto, autenticação de operador, handoff e sync comercial
Domínio	`src/core/domain/`	`Session`, `Message`, enums, catálogo, transições; sem chamadas HTTP
Agentes	`src/core/agents/`	Construir prompts e histórico para `LLMClient`; não persistem sessão nem fazem chamadas CRM
Integrações	`src/core/integrations/`	Protocols, adapters reais/stubs, factories e repositories DynamoDB
Conhecimento	`src/core/knowledge_base/`	Catálogo empacotado e overrides administrativos versionados
UI	`src/emulator/app.py`, `src/emulator/templates/`	Ferramentas locais, administração e atendimento humano, conforme flags e autenticação
Jobs	`src/crm_sync/app.py`, `src/handoff_renotify/app.py`, `src/admin_export/app.py`	Projeção comercial, renotificação e exportação administrativa
Infraestrutura	`template.yaml`	Lambdas, tabela, FIFO, DLQ, APIs, agendamentos e permissões

core.integrations.factory.build_dependencies() é a composição central. Seu objeto imutável Dependencies contém settings, KB, LLM, WhatsApp, CRM, eGestor, handoff, repositories e invocador. Testes podem injetar um AgentInvoker determinístico e uma tabela Moto sem invocar OpenAI.

Fronteiras importantes¶

A sessão ativa é identificada por telefone; whatsapp_instance é atributo da sessão. As chaves e o grupo FIFO não incluem a instância. O mesmo telefone não possui isolamento de sessões simultâneas por instância neste modelo.
O webhook registra todos os eventos traduzidos de um lote Meta antes de roteá-los. Isso permite invalidar uma resposta antiga mesmo quando a nova mensagem será atendida por uma rota síncrona.
HANDOFF_PENDING interrompe os agentes imediatamente. O webhook grava novos textos/mídias na conversa e envia uma confirmação fixa de recebimento; HUMAN somente grava a entrada, sem resposta automática.
Horário comercial modifica instruções e disponibilidade humana. Não impede que a IA faça triagem/coleta fora do horário.
A integração WhatsApp real é opt-in; o factory retorna stub quando desabilitada. OpenAI não possui um modo stub automático equivalente em build_dependencies(); testes substituem o invocador/cliente.

Consistência e efeitos externos¶

A persistência usa transações e condições no DynamoDB para impedir que uma resposta do bot sobrescreva um atendimento assumido por humano ou uma mensagem mais recente. Essa proteção é detalhada em Orchestrator e SQS. Ela não transforma uma chamada HTTP em transação distribuída: existe uma janela entre a última verificação e o envio ao provider. A confirmação protege o ponto anterior à primeira mutação externa e termina a sequência iniciada para reduzir cadastros parciais.

O estado comercial é independente: CrmSyncRepository guarda revisão desejada, revisão confirmada, IDs externos e situação de retry. O encerramento da conversa pode estar persistido enquanto o CRM ainda está PENDING, BLOCKED ou UNCERTAIN. Veja CRM.

Falhas e verificação¶

Contrato de agente inválido, após tentativa de reparo, termina em handoff visível. Erros de infraestrutura que escapam ao caso de uso tornam o registro SQS elegível a retry. Resposta já persistida pode ser reenviada sem executar a IA novamente. Um corpo SQS malformado é registrado como bad_sqs_body e descartado sem retry.

Fontes de regressão: tests/unit/application/test_process_message_use_case.py, tests/unit/lambdas/test_webhook_handler.py, tests/unit/lambdas/test_orchestrator.py, tests/unit/integrations/test_dynamodb_repos.py e tests/unit/application/test_crm_sync.py. A existência desses testes comprova quais casos estão especificados; não equivale à validação de um ambiente remoto.

Como alterar¶

Comece pelo contrato de domínio quando mudar estados ou campos. Se a mudança afeta ação do modelo, atualize enum, dispatcher, prompt e teste de conversa juntos. Se afeta transporte, preserve receipts e guards de concorrência. Para adicionar provider, siga nova integração. Para alterar um serviço, use o catálogo.

Divergência documental

Comentários ainda descrevem fases de MVP, integrações stub e debounce antigo. O código atual contém clientes reais, FIFO imediato, painel humano, administração dinâmica e sync comercial. Esses comentários não devem ser usados como inventário de capacidades.