Safe Delivery Outbox

Implementacao do padrao Transactional Outbox com BullMQ para garantir entrega confiavel de eventos entre o modelo de escrita e o processamento assincrono.

Visao Geral

Este projeto oferece uma base orientada a producao para fluxos assincronos em que uma operacao HTTP de escrita persiste dados de negocio e publica um evento de integracao com seguranca.

Fluxo principal:

1. A API recebe POST /orders.
2. O service grava orders e outbox na mesma transacao de banco.
3. O relay faz claim dos eventos pendentes do outbox e publica no BullMQ com jobId idempotente.
4. O worker consome os jobs no Redis e executa o processamento.

Por Que Outbox + BullMQ

• Escrita atomica + registro de evento: evita perda de eventos entre commit no banco e publicacao na fila.
• Relay confiavel: estrategia de polling + claim evita duplicacao concorrente entre instancias de relay.
• Publicacao idempotente na fila: jobId estavel por evento evita criacao de jobs duplicados.
• Simplicidade operacional: separacao clara entre processos de API, relay e worker.

Tech Stack

• Node.js + TypeScript
• Express
• Drizzle ORM + PostgreSQL
• BullMQ + Redis
• Pino (logs de aplicacao e requests)
• Zod (validacao de entrada e ambiente)
• CORS + Express Rate Limit (protecao de API)

Estrutura do Projeto

src/
  infra/
    http/        # bootstrap da API, rotas e middlewares
    relay/       # dispatcher do outbox e loop de publicacao
    worker/      # consumidor BullMQ
    database/    # conexao Drizzle, schema e migracao SQL
    messaging/   # fila BullMQ e conexao Redis
  modules/
    orders/      # caso de uso de pedido, validacao e repositorio
    outbox/      # persistencia de outbox e transicoes de estado
  shared/
    env.ts       # schema de ambiente
    logger.ts    # configuracao de logger

Variaveis de Ambiente

Copie .env.example para .env e configure:

• NODE_ENV
• APP_PORT
• LOG_LEVEL
• DB_HOST, DB_PORT, DB_NAME, DB_USER, DB_PASSWORD
• REDIS_HOST, REDIS_PORT

Execucao

Processos locais

pnpm install
pnpm start:server
pnpm start:relay
pnpm start:worker

Docker Compose

docker compose up --build

Observacao: compose.yml espera uma rede Docker existente chamada infra_net e instancias de PostgreSQL/Redis acessiveis com base no .env.

Banco de Dados

Aplique o schema SQL em:

• src/infra/database/migration/schema.sql

Ele inclui:

• tabela orders
• tabela outbox
• enum outbox_status (pending, processing, processed, failed)
• indice otimizado para leitura de eventos pendentes no relay do outbox

API

• GET / -> status de saude
• POST /orders -> cria um pedido e enfileira evento de integracao via relay de outbox

Protecoes HTTP

• cors habilitado para controle de acesso entre origens.
• express-rate-limit com janela de 1 minuto e limite de 60 requisicoes por IP.

Exemplo de payload:

{
  "customerEmail": "customer@company.com",
  "amount": "149.90"
}