Pular para o conteúdo
ZYNQORALABS
SW · Demonstração interna

Relay MeshHub de integração orientado a eventos

Arquitetura de referência para sincronizar pedidos entre e-commerce, ERP, CRM e provedor de pagamentos com retentativas seguras, sem efeitos duplicados e com reprocessamento auditável.

Tecnologias
TypeScript · PostgreSQL · Message broker · OpenTelemetry
Demonstra
  • Outbox transacional
  • Sagas com compensação
  • Idempotência ponta a ponta
  • Operação sem engenheiro

O desafio

  1. 01

    Webhooks chegam duplicados, fora de ordem ou não chegam. Sistemas externos ficam indisponíveis por minutos.

  2. 02

    Gravar no banco e publicar uma mensagem são duas operações; se uma falhar, os sistemas divergem.

  3. 03

    Quando algo dá errado, o time de operações precisa ver o que aconteceu e reprocessar sem chamar um engenheiro.

Restrições

  • Sistemas legados
  • Sem efeitos duplicados
  • Operável por não engenheiros

Arquitetura

Entradas verificadas e deduplicadas, saga com compensações e saída via outbox transacional.Fig. 01 · Relay Mesh

Componentes

E-commerce
Origem dos pedidos via webhook.
Payments
Confirmações de pagamento via webhook.
Verified inbox
Valida assinatura HMAC e descarta duplicatas pelo ID do evento.
Order saga
Máquina de estados com compensações para cada passo.
Outbox
Mensagens gravadas na mesma transação do estado.
ERP
Recebe pedidos e faturas com chave de idempotência.
CRM
Atualiza o histórico do cliente.
Dead letters
Falhas definitivas com contexto completo e botão de reprocessar.

Decisões de engenharia

D1Outbox transacional

Escolha
O estado do pedido e a mensagem a publicar são gravados na mesma transação; um relay publica depois.
Alternativa descartada
Gravar no banco e publicar no broker em sequência.
Por quê
Escritas duplas falham de forma parcial. Com a outbox, ou as duas coisas acontecem ou nenhuma acontece.

D2Pelo menos uma vez + consumidores idempotentes

Escolha
Toda chamada externa leva uma chave de idempotência derivada do evento de origem.
Alternativa descartada
Perseguir entrega exatamente uma vez no transporte.
Por quê
Exatamente uma vez na rede não existe na prática. Exatamente uma vez no efeito, sim, com idempotência.

D3Saga em vez de transação distribuída

Escolha
Cada passo tem uma compensação explícita (cancelar reserva, estornar fatura).
Alternativa descartada
Two-phase commit entre sistemas.
Por quê
ERPs e provedores de pagamento não participam de 2PC. Compensações são o que esses sistemas oferecem de fato.

D4Reprocessamento como funcionalidade

Escolha
Fila de mensagens mortas com contexto, motivo e reprocessamento pela interface.
Alternativa descartada
Logs para um engenheiro investigar.
Por quê
Falhas de integração são rotina. Quem opera precisa resolvê-las sem depender do time de desenvolvimento.

Detalhes de implementação

Webhooks entram por um endpoint que valida a assinatura, grava o evento bruto na inbox com o ID externo como chave única e responde rápido. O processamento acontece depois, fora do caminho da requisição.

A saga avança um passo por vez e grava, na mesma transação, o novo estado e as mensagens de saída. Um relay lê a outbox em ordem e publica com retentativas exponenciais.

Cada mensagem carrega um trace ID desde o webhook de origem, então a visão de operações mostra a história completa de um pedido em uma linha do tempo.

saga/advance.tsTrecho representativo
export async function advance(orderId: string, event: DomainEvent) {
  await db.transaction(async (tx) => {
    const saga = await tx.sagas.lockById(orderId); // SELECT … FOR UPDATE
    const step = saga.transition(event); // pure: returns next state + commands
    await tx.sagas.save(saga.id, step.state);
    for (const command of step.commands) {
      await tx.outbox.insert({
        topic: command.topic,
        payload: command.payload,
        // Same source event => same key => the ERP applies it once.
        idempotencyKey: `${event.id}:${command.topic}`,
        traceId: event.traceId,
      });
    }
  });
}

Resultados

Não aplicável. Por ser uma demonstração interna, não há métricas de produção verificadas a relatar, e não publicamos números estimados como se fossem resultados.

Tem um problema parecido?

Conte o contexto. Discutimos a arquitetura antes de qualquer proposta comercial.

Próximo estudoLedgerlineInteligência contratual com recuperação avaliada
01Quem é você

Usamos apenas para responder a esta solicitação.

02O projeto

O problema, o que já existe hoje e o que seria sucesso. Não inclua senhas ou dados pessoais de terceiros.

03Escopo

Usamos estes dados apenas para avaliar e responder à sua solicitação. Não vendemos nem compartilhamos com terceiros para marketing. Detalhes na política de privacidade.