Payment Processing, DDD, Hexagonal Architecture, DomoActors-style Actors and KurrentDB

Este proyecto es una PoC de Payment Processing. Implementa una arquitectura basada en Domain-Driven Design, Arquitectura Hexagonal, CQRS, Event Sourcing y un modelo de actores inspirado en DomoActors para procesar comandos de forma secuencial por agregado.

Objetivo del dominio

El microservicio gestiona el ciclo de vida de un pago:

1. Iniciar un pago.
2. Autorizarlo.
3. Capturarlo.
4. Fallarlo.
5. Cancelarlo.
6. Reembolsarlo.
7. Consultar su estado reconstruido desde eventos.
8. Consultar el historial de eventos.

Aggregate principal

El agregado raíz es Payment.

Estados posibles:

• NEW
• AUTHORIZED
• CAPTURED
• FAILED
• REFUNDED
• CANCELLED

Comandos

• InitiatePaymentCommand
• AuthorizePaymentCommand
• CapturePaymentCommand
• FailPaymentCommand
• RefundPaymentCommand
• CancelPaymentCommand

Eventos de dominio

• PaymentInitiated
• PaymentAuthorized
• PaymentCaptured
• PaymentFailed
• PaymentRefunded
• PaymentCancelled

Cada cambio de estado se guarda como evento en KurrentDB. El estado actual del pago no se persiste como una fila tradicional, sino que se reconstruye aplicando su historial de eventos.

Arquitectura

src/main/java/com/example/payments
├── domain
│   ├── model
│   ├── commands
│   ├── events
│   └── ports
├── application
│   ├── actors
│   └── service
├── infrastructure
│   └── kurrentdb
├── adapters
│   └── rest
└── config

Flujo

REST Controller
    ↓
Application Service
    ↓
Payment Actor
    ↓
Payment Aggregate
    ↓
Domain Events
    ↓
KurrentDB Event Store

Modelo de actores

El proyecto incluye un PaymentActorSystem y un PaymentActor por paymentId. La finalidad es procesar los comandos de un mismo pago de forma secuencial, evitando condiciones de carrera sobre el agregado.

Este enfoque está inspirado en DomoActors, pero adaptado a Java mediante un actor simple basado en ConcurrentHashMap y ReentrantLock.

Levantar infraestructura

cd infraestructura
docker compose up -d

KurrentDB quedará disponible en:

http://localhost:2113

Ejecutar el microservicio

mvn spring-boot:run

El servicio queda disponible en:

http://localhost:8080

Swagger UI:

http://localhost:8080/swagger-ui.html

Endpoints REST

Iniciar pago

POST /payments/v1/payments

Request:

{
  "merchantId": "merchant-001",
  "customerId": "customer-9001",
  "amount": 150.75,
  "currency": "PEN",
  "paymentMethod": "CARD",
  "orderId": "order-2026-0001"
}

Autorizar pago

POST /payments/v1/payments/{paymentId}/authorizations

{
  "authorizationCode": "AUTH-123456"
}

Capturar pago

POST /payments/v1/payments/{paymentId}/captures

{
  "captureReference": "CAP-987654"
}

Reembolsar pago

POST /payments/v1/payments/{paymentId}/refunds

{
  "amount": 50.00,
  "reason": "Customer partial refund request"
}

Cancelar pago

POST /payments/v1/payments/{paymentId}/cancellations

{
  "reason": "Customer cancelled order before capture"
}

Consultar pago

GET /payments/v1/payments/{paymentId}

Consultar eventos

GET /payments/v1/payments/{paymentId}/events

Reglas de negocio principales

• Un pago inicia en estado NEW.
• Solo un pago NEW puede ser autorizado.
• Solo un pago AUTHORIZED puede ser capturado.
• Solo un pago CAPTURED puede ser reembolsado.
• Un pago NEW o AUTHORIZED puede ser cancelado.
• Un pago CAPTURED o REFUNDED no puede fallarse.

Configuración

Archivo:

src/main/resources/application.yml

server:
  port: 8080

spring:
  application:
    name: payment-processing-kurrentdb-java25

kurrentdb:
  connection-string: kurrentdb://localhost:2113?tls=false

Probar

Levanta KurrentDB:

cd infraestructura
docker compose up -d

Verifica que esté arriba:

docker ps

KurrentDB queda en: http://localhost:2113

Luego levanta el microservicio:

cd ..
mvn spring-boot:run

El API queda en:

http://localhost:8080

Swagger: http://localhost:8080/swagger-ui.html

Docker files incluidos:

infraestructura/
├── docker-compose.yml   # levanta KurrentDB
├── Dockerfile           # construye la imagen del microservicio Java
├── requests/            # ejemplos de requests
└── responses/           # ejemplos de responses

Para probar:

curl -X POST http://localhost:8080/payments/v1/payments \
  -H "Content-Type: application/json" \
  -d @infraestructura/requests/01-initiate-payment.json