Recebimentos bancários em microsserviços, eventos e consistência transacional.
Sistema distribuído construído com Java 21 e Spring Boot para emissão, consulta, pagamento e notificação de boletos. O projeto aplica DDD, Arquitetura Hexagonal, CQRS e Transactional Outbox em um domínio financeiro com infraestrutura local e desenho de solução em AWS.
Visão Geral
O Received Bank organiza o domínio de recebimentos em serviços independentes e integrados por eventos. A escrita de boletos fica isolada do read model de consulta, o pagamento vem de um PSP/Banco externo e notificações reagem aos eventos publicados.
Fluxo completo de boleto: emissão pelo PJ Parceiro, pagamento pelo Cliente Pagador, consulta e notificação.
O boleto e o evento boleto.gerado são gravados na mesma transação PostgreSQL.
O query-service mantém consultas otimizadas sem ler o banco do serviço de escrita.
Arquitetura AWS com EKS, MSK, SQS, RDS, ElastiCache, WAF, S3 e SNS/SES.
Stack Técnica
A base do projeto combina runtime moderno, mensageria, persistência relacional, cache de idempotência, infraestrutura como código e pipelines de validação.
| Camada | Tecnologias |
|---|---|
| Linguagem e runtime | Java 21, Spring Boot 3.2, Spring Cloud |
| Mensageria | Apache Kafka via Redpanda em ambiente local e Amazon MSK no desenho cloud |
| Dados | PostgreSQL 16 para escrita, Outbox e read model; Redis 7 para idempotência |
| Cloud | AWS EKS, API Gateway, SQS, SNS/SES, S3, WAF, RDS, ElastiCache e MSK |
| Infraestrutura como código | Terraform para provisionamento AWS e manifests Kubernetes para EKS |
| Observabilidade e CI | Spring Actuator, health checks por serviço, Maven multi-module e GitHub Actions |
Fluxo Operacional
A jornada separa a emissão do boleto pelo PJ Parceiro, o pagamento no PSP/Banco externo, o webhook de retorno, a validação do pagamento, a atualização do read model e a notificação final.
POST /boletos e o boleto-service cria o agregado.boleto.gerado são persistidos na mesma transação./simulacoes/registradora/boletos.payment-service.query-service atualiza o read model a partir dos eventos.notification-service publica notificacao.enviada.Arquitetura AWS
O desenho organiza PJ Parceiro, Cliente Pagador, PSP/Banco externo, borda segura, SQS, EKS, MSK, dados, serviços gerenciados e fluxos numerados de emissão e pagamento.
| Camada | Local | AWS |
|---|---|---|
| Borda e segurança | REST local direto | AWS WAF e API Gateway para emissão de boleto e webhook de pagamento |
| Entrada assíncrona | Chamadas REST para os serviços | SQS boleto-generation com DLQ para emissão de boletos |
| Compute | Docker Compose | Amazon EKS com quatro microsserviços e outbox worker |
| Dados | PostgreSQL e Redis em containers | RDS PostgreSQL e ElastiCache Redis |
| Eventos | Redpanda compatível com Kafka | Amazon MSK |
| Serviços gerenciados | Variáveis de ambiente e Actuator | CloudWatch, Secrets Manager, IAM/IRSA, ECR e SNS/SES |
Padrões Aplicados
As escolhas arquiteturais foram usadas para reduzir acoplamento, preservar consistência, facilitar testes e manter cada bounded context com responsabilidades claras.
Cada microsserviço representa um bounded context. As regras ficam em domain, os casos de uso em application e HTTP, Kafka e JPA entram como adapters.
boleto-service concentra o modelo de escrita. query-service consome eventos e mantém um read model independente para consultas.
O outbox-worker publica eventos gravados junto com a transação de negócio, evitando inconsistências entre banco e Kafka.
SQS absorve picos na emissão, DLQ isola falhas, Kafka DLT apoia reprocessamento e Redis sustenta idempotência.
Decisões Arquiteturais
As ADRs registram contexto, alternativas consideradas e consequências das decisões centrais do projeto.
Outbox foi escolhido para garantir uma transação ACID cobrindo boleto e evento, sem coordenação distribuída.
Separação lógica em desenvolvimento, com caminho claro para separar fisicamente em alto volume.
Entrada assíncrona absorve picos e permite resposta 202 Accepted com processamento posterior.
Casos de uso testáveis sem Spring, banco ou Kafka, com adapters substituíveis.
Arquivo completo: received-bank-services/docs/architecture/ARCHITECTURE_DECISION_RECORD.md
Serviços
O módulo received-bank-services agrupa os microsserviços Maven e os commons compartilhados do domínio e infraestrutura.
| Serviço | Porta | Responsabilidade | Eventos |
|---|---|---|---|
| boleto-service | 8081 |
Cria e consulta boletos no modelo de escrita, aplica regras de domínio e grava eventos no Outbox. | Produz boleto.gerado |
| query-service | 8082 |
Mantém o read model de boletos e expõe consultas por boleto ou status. | Consome eventos de domínio |
| payment-service | 8083 |
Consome boletos gerados, recebe webhook de pagamento vindo do PSP/Banco externo e valida valor e vencimento. | Produz pagamento.efetivado ou pagamento.rejeitado |
| notification-service | 8084 |
Consome eventos de boleto e pagamento para emitir notificações do resultado. | Produz notificacao.enviada |
APIs Principais
Os endpoints cobrem a jornada de boleto de ponta a ponta e podem ser exercitados pelas coleções versionadas de Postman e Insomnia.
| Método | Endpoint | Serviço | Descrição |
|---|---|---|---|
POST | /boletos | boleto-service | Cria um boleto e retorna 201 Created. |
GET | /boletos/{id} | boleto-service | Consulta um boleto pelo identificador no modelo de escrita. |
POST | /simulacoes/registradora/boletos | boleto-service | Simula registro externo de boleto. |
POST | /simulacoes/pagamentos | payment-service | Simula, localmente, o webhook de pagamento que viria do PSP/Banco externo. |
GET | /consultas/boletos | query-service | Lista boletos do read model, com filtro opcional por status. |
GET | /consultas/boletos/{boletoId} | query-service | Consulta um boleto no read model. |
http://localhost:8081/actuator/health
http://localhost:8082/actuator/health
http://localhost:8083/actuator/health
http://localhost:8084/actuator/health
Ambiente Local
O ambiente local usa Maven Wrapper e Docker Compose para subir os serviços e dependências de infraestrutura.
cd received-bank-services
./mvnw clean test
docker compose up --buildColeções de API
Importe uma das coleções para executar a jornada completa: health checks, emissão do boleto, retorno simulado de pagamento aprovado, consulta CQRS e cenário de rejeição por regra de negócio.
Cloud e Infraestrutura como Código
Use os comandos abaixo para inicializar o Terraform, revisar o plano de execução e provisionar a infraestrutura AWS do projeto com as credenciais configuradas no ambiente local.
| Área | Recursos |
|---|---|
| Rede e compute | VPC, subnets públicas e privadas, NAT Gateway, EKS Cluster, node group e ALB Ingress Controller. |
| Dados e mensagens | RDS PostgreSQL, ElastiCache Redis, SQS com DLQ, Amazon MSK, S3 para documentos e backups. |
| Segurança | Security Groups, IAM roles com IRSA por service account, Secrets Manager e Kubernetes Secrets de exemplo. |
| Observabilidade | CloudWatch Log Groups, métricas via Actuator e Prometheus, alertas via SNS. |
cd received-bank-services/infra/aws/terraform
cp terraform.tfvars.example terraform.tfvars
terraform init
terraform plan
terraform applyterraform init prepara o diretório e baixa os providers necessários.
terraform plan mostra quais recursos serão criados, alterados ou removidos.
terraform apply executa o plano e cria os recursos na conta AWS ativa.
Esses comandos usam as credenciais AWS configuradas no ambiente de quem executa. Eles não usam uma conta fixa do repositório. Ao rodar terraform apply, os recursos serão criados na conta AWS ativa e podem gerar custos.