Pular para conteúdo

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 Accepted indica 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