order-flow-platform

Plataforma backend de pedidos e entregas em tempo real, construída como monorepo Java 21/Spring Boot 3 para demonstrar arquitetura event-driven, microsserviços, Outbox Pattern, idempotência, Saga coreografada, CQRS parcial, LocalStack/AWS e infraestrutura como código.

Visão geral

O sistema simula um fluxo de e-commerce/logística em alta escala:

1. order-service recebe o pedido e persiste OrderCreated no outbox.
2. O publisher assíncrono publica o evento em SNS.
3. inventory-service reserva estoque via SQS.
4. payment-service processa pagamento.
5. order-service confirma ou cancela o pedido conforme o resultado.
6. fulfillment-service inicia separação e publica pacote pronto.
7. delivery-service cria tracking e conclui entrega simulada.
8. notification-service simula notificação.
9. tracking-query-service mantém uma projeção otimizada de leitura.

Arquitetura

O projeto usa:

• Java 21 e Spring Boot 3.x.
• Maven multi-module.
• PostgreSQL para os serviços relacionais.
• Flyway para migrations.
• SNS/SQS via AWS SDK v2, com LocalStack para execução local.
• Outbox Pattern no order-service.
• Consumers idempotentes com tabela processed_events nos serviços persistentes.
• Saga coreografada por eventos.
• CQRS parcial via tracking-query-service.
• Resilience4j no simulador de pagamento.
• Micrometer/Actuator para health, métricas e Prometheus.
• Terraform modular para AWS dev.
• GitHub Actions para CI, plan e CD dev.

Estrutura

services/
  common-events/
  order-service/
  inventory-service/
  payment-service/
  fulfillment-service/
  delivery-service/
  notification-service/
  tracking-query-service/
docs/architecture/
infra/terraform/
localstack/
scripts/

Microsserviços

• order-service: API de pedidos, agregado de domínio, outbox, consumo de resultados de inventário, pagamento e entrega.
• inventory-service: estoque, reserva transacional com lock, liberação por compensação.
• payment-service: simulação de pagamento idempotente, regra de alto valor configurável.
• fulfillment-service: separação/picking simulada.
• delivery-service: criação e atualização de tracking de entrega.
• notification-service: simulação de e-mail/SMS/push por evento.
• tracking-query-service: projeção consolidada para leitura rápida.

APIs principais

POST /orders
GET /orders/{orderId}
POST /orders/{orderId}/cancel
POST /products/{productId}/stock
GET /products/{productId}/stock
GET /tracking/orders/{orderId}

Exemplo de criação:

curl -X POST http://localhost:8081/orders \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cst-123",
    "paymentMethod": "CREDIT_CARD",
    "items": [
      {"productId": "prd-001", "quantity": 2, "unitPrice": 99.90}
    ]
  }'

Como rodar localmente

Pré-requisitos:

• Docker e Docker Compose.
• Java 21 para execução fora de containers.
• Maven 3.9+.

Suba a stack:

docker compose up --build

Carregue estoque antes de criar pedidos:

curl -X POST http://localhost:8082/products/prd-001/stock \
  -H "Content-Type: application/json" \
  -d '{"quantity": 100}'

Consulte tracking:

curl http://localhost:8087/tracking/orders/{orderId}

Testes

mvn verify

Para rodar também os testes de integração com Testcontainers:

mvn verify -Pintegration-tests

O projeto inclui exemplos de:

• Testes unitários de domínio.
• Testes de arquitetura com ArchUnit.
• Estrutura para integração com PostgreSQL/Testcontainers.
• Estrutura para mensageria LocalStack/Testcontainers.

LocalStack

localstack/init-aws.sh roda automaticamente no docker compose up e cria:

• Tópicos SNS por domínio.
• Filas SQS principais.
• DLQs para cada fila.
• Assinaturas filtradas por atributo eventType.
• Tabelas DynamoDB para tracking, idempotência de pagamento e tentativas de notificação.
• Bucket S3 de artefatos.
• Repositórios ECR locais.
• Log groups CloudWatch Logs.
• Secrets locais para JWT, notificação e bancos PostgreSQL.

Deploy AWS

O Terraform em infra/terraform/environments/dev provisiona:

• VPC pública/privada.
• Repositórios ECR.
• Tópicos SNS.
• Filas SQS com DLQ, policies e subscriptions SNS filtradas por evento.
• DynamoDB tables.
• Aurora PostgreSQL Serverless v2.
• ElastiCache Redis.
• Log groups CloudWatch.
• Roles IAM de execução e runtime ECS.
• ECS Cluster.
• ECS Task Definitions e ECS Services Fargate para todos os microsserviços.
• ALB para APIs HTTP.
• API Gateway HTTP apontando para o ALB.
• Secrets Manager para JWT e provider de notificação.

Exemplo:

cd infra/terraform/environments/dev
terraform init
terraform plan -var image_tag=latest

Decisões arquiteturais

• Eventos usam envelope comum com eventId, eventType, aggregateId, aggregateType, occurredAt, version e payload.
• O order-service usa outbox para não publicar eventos antes do commit do pedido.
• Consumers persistentes usam processed_events para idempotência.
• A compensação de pagamento recusado é coreografada: PaymentRejected libera estoque e cancela pedido.
• O read model de tracking é separado do modelo transacional.

Trade-offs

• DynamoDB foi preparado, mas a primeira versão usa PostgreSQL no tracking para manter o ambiente local mais simples.
• Fulfillment, delivery e notification usam idempotência em memória nesta base inicial; produção deve persistir esse controle.
• Terraform dev provisiona a stack AWS completa para desenvolvimento, com defaults conservadores de capacidade.
• Segurança JWT está preparada como tópico de evolução; a primeira versão foca no fluxo backend/event-driven.

Roadmap

• Persistir idempotência nos serviços sem banco.
• Adicionar Spring Security/JWT local.
• Migrar tracking para DynamoDB.
• Endurecer ECS, ALB/API Gateway e Aurora para produção multi-AZ com WAF e alarmes.
• Adicionar tracing OpenTelemetry end-to-end.
• Adicionar contratos de eventos e testes de compatibilidade.
• Criar smoke tests pós-deploy.