Arquitetura e Comunicação
O EcomSmart Agents é executado como um conjunto de serviços Docker na rede privada ecomsmart-net. O Nginx e o Cloudflare Tunnel fazem a entrada pública; as chamadas entre serviços usam HTTP na rede interna.
flowchart TB
meta[Meta / WhatsApp Cloud API] --> tunnel[Cloudflare Tunnel]
web[Usuários web] --> tunnel
woo[WooCommerce da loja] --> tunnel
tunnel --> gateway[Nginx]
gateway --> wpp[WhatsApp Entrypoint]
gateway --> panel[Painel]
gateway --> landing[Landing]
gateway --> marketing[Marketing Campaigns]
gateway --> wrapper[WooCommerce Wrapper]
wpp --> b2c[Agente B2C]
wpp --> b2b[Agente B2B]
b2c --> ai[GenAI Wrapper]
b2b --> ai
b2c --> wrapper
b2b --> wrapper
panel --> platform[Frontend Entrypoint]
platform --> wpp
platform --> wrapper
ai --> vectors[Weaviate]
ai --> llm[Provedor de IA]
wrapper --> woo
Da borda para a rede interna
O tráfego público deve chegar pelo gateway. Ele direciona cada domínio e rota ao serviço adequado, incluindo os webhooks de WhatsApp, o painel, a landing page, a documentação de campanhas e o webhook de produtos do WooCommerce.
Os demais serviços não precisam ser usados como endpoints públicos. Eles se comunicam pelo nome do serviço Docker, com URLs como http://b2c:10001, dentro da rede privada.
Uma exceção importante
O woocommerce-wrapper recebe o webhook de produto do WooCommerce pela rota pública encaminhada pelo Nginx. Esse é o caminho usado para manter o índice de produtos atualizado.
Serviços de aplicação
| Grupo | Serviços | Papel na comunicação |
|---|---|---|
| Canais | whatsapp-entrypoint, panel, landing |
Recebem ou apresentam a experiência ao usuário. |
| Orquestração | b2c, b2b, frontend-entrypoint |
Interpretam eventos, mantêm o contexto da conversa e coordenam operações. |
| Integrações | woocommerce-wrapper, flow-gateway, marketing-campaigns |
Isolam integrações com WooCommerce, rotas web e campanhas. |
| IA | genai-wrapper |
Centraliza modelos de linguagem, imagens, embeddings e busca vetorial. |
| Trabalho em segundo plano | conversation-outcome-worker |
Processa resultados de conversa sem bloquear o recebimento de webhooks. |
As páginas em Referência de Serviços aprofundarão responsabilidades, dependências e rotas de cada serviço.
Dois tipos de interação no WhatsApp
flowchart LR
meta[Meta] --> wpp[WhatsApp Entrypoint]
wpp --> event[Evento de conversa]
wpp --> flow[Interação de Flow]
event --> agent[Agente B2C ou B2B]
flow --> agent
agent --> wpp
wpp --> meta
| Interação | Quando acontece | Como é tratada |
|---|---|---|
| Evento de conversa | Mensagem, botão, catálogo ou status de entrega | O agente recebe o evento e atualiza a máquina de estados da conversa. |
| Interação de Flow | Formulário ou tela dentro do WhatsApp | O whatsapp-entrypoint processa a criptografia e encaminha o payload já aberto ao agente, que devolve a próxima tela. |
Os endpoints internos que recebem eventos e Flow exchanges exigem uma chave interna. O cliente ou lojista nunca chama esses endpoints diretamente.
Como os contratos são mantidos
- Os contratos de requisição e resposta compartilhados ficam em
contracts/. - Serviços consumidores devem usar os clientes internos e os schemas disponíveis, em vez de reproduzir formatos de payload manualmente.
- Uma alteração de contrato deve ser compatível durante o rollout ou publicada de forma coordenada entre quem fornece e quem consome a interface.
- O retorno
202 Acceptedindica que o serviço aceitou um evento para processamento; não é uma confirmação de que toda a jornada posterior terminou.
Leitura do diagrama
- Setas para o gateway representam entrada pública controlada.
- Setas entre serviços representam chamadas HTTP internas.
- WooCommerce, Meta e provedores de IA são sistemas externos; indisponibilidades neles devem ser tratadas como falhas de integração, não como erro do usuário.
Próximas leituras
- Visão da Plataforma: objetivos e domínios da solução.
- Dados, Segurança e Configuração: persistência, isolamento e configuração do ambiente.
- Observabilidade e Diagnóstico: como investigar falhas entre os componentes.