Desafio Itaú - Financial Transaction Processing

High-performance transaction processing system with Spring Boot consumer and Go producer.

🚀 Quick Start

Prerequisites

• Docker and Docker Compose
• AWS CLI (for local testing)

Local Development

1. Clone the repository

   git clone https://github.com/leo-the-nardo/desafio-itau
   cd desafio-itau

2. Start all services

   cd _infra-local
   docker-compose up -d

3. Access services

   • Consumer API: http://localhost:8080
   • API Documentation: http://localhost:8080/swagger-ui.html
   • Grafana: http://localhost:3000
   • Health Check: http://localhost:8080/actuator/health
   • Metrics: http://localhost:8080/actuator/prometheus
   • Prometheus: http://localhost:9090

Testing the API

1. Using curl

   # Get account balance
   curl http://localhost:8080/balances/5b19c8b6-0cc4-4c72-a989-0c2ee15fa975
   
   # Health check
   curl http://localhost:8080/actuator/health

🏗️ Architecture

Key Components

• Producer: Go application generating synthetic financial transactions
• SQS: Message queue for transaction processing
• Consumer: Spring Boot application consuming transactions and updating balances
• DynamoDB: NoSQL database storing processed transactions
• Monitoring: Grafana + Prometheus for observability

📊 API Documentation

Endpoints

Method	Endpoint	Description
GET	/balances/{accountId}	Get account balance
GET	/actuator/health	Health check
GET	/actuator/prometheus	Metrics
GET	/swagger-ui.html	API documentation

Response Format

{
  "id": "5b19c8b6-0cc4-4c72-a989-0c2ee15fa975",
  "owner": "315e3cfe-f4af-4cd2-b298-a449e614349a",
  "balance": {
    "amount": 183.12,
    "currency": "BRL"
  },
  "updated_at": "2025-07-05T18:04:13.433-03:00"
}

🎯 Principles

Pattern	Implementation	Benefits
Microservices Architecture	Producer (Go) + Consumer (Spring Boot)	Independent scaling, fault isolation
Event-Driven Architecture	SQS as message broker	Loose coupling, scalability
Hexagonal Architecture	Service layer separated from repository	Testability, maintainability
Circuit Breaker	@CircuitBreaker in SQS listener	Fault tolerance
Retry with Exponential Backoff	@Retry with backoff configuration	Transient failure handling
Bulkhead	Batch processing with size limits	Resource protection
Dead Letter Queue	SQS DLQ configuration	Message persistence
Manual Acknowledgment	BatchAcknowledgement in listener	Partial batch success
Single Table Design	processed_transactions table	Query efficiency
Composite Key	PK (partition) + SK (sort) structure	Natural sorting
Batch Processing	BatchWriteItem for DynamoDB	Performance optimization
Repository Pattern	ProcessedTransactionRepository	Testability, maintainability
Service Layer	BalanceService	Separation of concerns
Builder Pattern	Lombok @Builder	Object construction flexibility
Record Pattern	BalanceSqsEvent, AccountBalanceResponse	Immutability
Dependency Injection	Spring's constructor injection	Loose coupling
Factory Pattern	Spring's @Bean methods	Object creation abstraction
Container Orchestration	Kubernetes with EKS	Scalability, high availability
Infrastructure as Code	Terraform for AWS resources	Version control
GitOps	GitHub Actions workflows	Audit trail
Canary Deployment	Istio VirtualService	Risk mitigation
Metrics Collection	Micrometer + Prometheus	Performance monitoring
Distributed Tracing	OpenTelemetry	Performance analysis
Health Checks	Spring Boot Actuator	Early failure detection
Test Pyramid	Unit, integration, E2E layers	Fast feedback
Test Containers	TestContainers + LocalStack	Realistic testing
Mock Pattern	Mockito for unit tests	Fast tests
Principle of Least Privilege	IAM roles and policies	Security
Configuration Externalization	Environment variables	Environment flexibility
Architecture Decision Records	ADR files in docs/adr/	Decision transparency
Living Documentation	OpenAPI annotations, README	Accuracy

Total Patterns Implemented: 33

🚀 Production Deployment

Infrastructure Setup

1. Deploy AWS Infrastructure

   cd _infra-prod/terraform
   
   # Set required variables
   export TF_VAR_cluster_oidc_provider="oidc.eks.sa-east-1.amazonaws.com/id/YOUR_CLUSTER_ID"
   export TF_VAR_environment="prod"
   export TF_VAR_aws_region="sa-east-1"
   
   terraform init && terraform apply

2. Deploy Application

   cd _infra-prod/k8s-manifests/consumer
   
   # Update values.yaml with your configuration
   # Set imageName, tag, and other required values
   
   # Deploy with Helm
   helm install consumer ./helm \
     --namespace production \
     --create-namespace \
     --values production.yaml

Deployment Strategies

Istio-based Canary Deployment

• File: .github/workflows/istio-deployment.yml
• Strategy: Gradual traffic shifting using Istio VirtualService
• Features:
  • Automatic traffic splitting (10% → 25% → 50% → 100%)
  • Built-in monitoring and rollback
  • Istio-native traffic management
• Usage: Automatically triggered on main branch pushes

Istio Infrastructure

• VirtualService: _infra-prod/k8s-manifests/istio/virtual-service.yaml
• DestinationRules: _infra-prod/k8s-manifests/istio/destination-rules.yaml
• Features: Traffic splitting, circuit breaking, retry policies

Environment Variables

# AWS Configuration
AWS_ACCESS_KEY_ID=your_key
AWS_SECRET_ACCESS_KEY=your_secret
AWS_REGION=sa-east-1

# Application Configuration
SPRING_PROFILES_ACTIVE=prod
CLOUD_AWS_SQS_QUEUE_NAME=transacoes-financeiras-processadas

🧪 Testing

Running Tests

cd consumer

# Unit tests
./gradlew test

# Integration tests
./gradlew integrationTest

# All tests with coverage
./gradlew test jacocoTestReport

Test Coverage

• Unit Tests: Controller, Service, Repository layers
• Integration Tests: End-to-end API testing
• E2E Tests: Full system testing with TestContainers

📈 Monitoring & Observability

Metrics Available

• Application Metrics: Request rate, response time, error rate
• SQS Metrics: Message processing rate, queue depth
• DynamoDB Metrics: Read/write capacity, latency
• System Metrics: CPU, memory, disk usage

Dashboards

• Grafana: http://localhost:3000
  • Transaction processing rate
  • Error rates and response times
  • System resource utilization

Health Checks

• Application Health: /actuator/health
• Database Connectivity: DynamoDB health
• Queue Connectivity: SQS health

🔧 Development

Building the Application

cd consumer

# Build JAR
./gradlew build

# Run locally
./gradlew bootRun

# Build Docker image
docker build -t itau-consumer .

Hot Reload

The application supports hot reload during development:

./gradlew bootRun --continuous

Debugging

1. Local Development: Use IDE debugger with Spring Boot DevTools
2. Docker: Attach debugger to container
3. Production: Use distributed tracing with OpenTelemetry

🛡️ Security

Security Features

• Input Validation: All inputs validated and sanitized
• Error Handling: Secure error responses (no sensitive data exposure)
• Rate Limiting: Configurable rate limiting
• Security Scanning: Trivy vulnerability scanning in CI/CD

Best Practices

• Environment variables for sensitive configuration
• No hardcoded secrets
• Regular security updates
• Principle of least privilege

🔄 Resilience Patterns

Implemented Patterns

1. Circuit Breaker: Prevents cascading failures
2. Retry with Exponential Backoff: Handles transient failures
3. Bulkhead Pattern: Isolates failures
4. Dead Letter Queue: Handles failed messages
5. Health Checks: Proactive failure detection

Configuration

# Circuit Breaker
resilience4j.circuitbreaker.instances.sqsListenerCB:
  sliding-window-size: 10
  failure-rate-threshold: 50
  wait-duration-in-open-state: 30s

# Retry
resilience4j.retry.instances.sqsListenerRetry:
  max-attempts: 5
  wait-duration: 500ms
  exponential-backoff-multiplier: 2

📚 Documentation

Architecture Decision Records (ADRs)

• ADR-0001: Record Architecture Decisions
• ADR-0002: Microservices Architecture
• ADR-0003: AWS SQS Messaging
• ADR-0004: DynamoDB Storage
• ADR-0005: Spring Boot Consumer
• ADR-0007: Observability Stack
• ADR-0008: Resilience Patterns
• ADR-0009: Container Orchestration
• ADR-0010: Infrastructure as Code
• ADR-0011: Testing Strategy

API Documentation

• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI Spec: http://localhost:8080/api-docs

Performance Tuning

1. SQS Configuration

   spring.cloud.aws.sqs.listener.max-concurrent-messages: 20
   spring.cloud.aws.sqs.listener.max-messages-per-poll: 20

2. DynamoDB Configuration

   • Auto-scaling enabled
   • Read/Write capacity optimized

3. JVM Tuning

   -Xms512m -Xmx2g -XX:+UseG1GC

🚀 Production Deployment

Manual Deployment (Helm)

To manually deploy or upgrade the application using Helm:

cd _infra-prod/k8s-manifests/consumer

# Install or upgrade the application
helm upgrade --install consumer ./helm \
  --namespace production \
  --create-namespace \
  --values production.yaml

Manual Rollback (Helm)

To rollback to a previous release:

# List Helm release revisions
helm history consumer -n production

# Rollback to a specific revision (replace <REVISION> with the desired revision number)
helm rollback consumer <REVISION> -n production

Manual Traffic Management (Istio)

To manually adjust traffic split between stable and canary deployments:

# Example: Send 80% to stable, 20% to canary
kubectl patch virtualservice consumer-vs -n production --type='merge' -p='
  spec:
    http:
    - route:
      - destination:
          host: consumer-stable
          port:
            number: 8080
        weight: 80
      - destination:
          host: consumer-canary
          port:
            number: 8080
        weight: 20
'