payments-modernization-platform

Reference implementation: safely modernizing a mission-critical legacy payments/settlement core into a cloud-native, event-driven platform using the Strangler Fig pattern -- no big-bang rewrite. Demonstrates CQRS + event sourcing, an orchestration-based SAGA with compensation, transactional-outbox CDC, an Anti-Corruption Layer, and canary progressive delivery.

This is the anchor of the Enterprise Platform Reference Architecture. It distills a modernization playbook proven at global enterprise scale into a small, runnable system. See docs/INDUSTRY-APPLICABILITY.md for how the same patterns map to banking, healthcare claims, asset management, and retail.

Architecture

flowchart LR
  client[Clients] --> gw[strangler-gateway :8090]
  gw -->|"weighted: 90% -> shrinking"| legacy[legacy-core :8080]
  gw -->|"weighted: 10% -> growing"| ledger[ledger-service :8081]
  gw --> settle[settlement-orchestrator :8082]
  legacy -->|transactional outbox CDC| kafka[(Kafka / Redpanda)]
  ledger -->|domain events| kafka
  settle -->|REST + SAGA| ledger
  subgraph ledgerInternals [ledger-service: CQRS]
    es[Event store - write model] --> bp[Balance projection - read model]
  end

Loading

Modules

Module	Role	Patterns
common-events	Versioned event contracts on the backbone	Schema versioning, sealed types
legacy-core	Stand-in legacy monolith being strangled	Transactional outbox, CDC
ledger-service	New event-sourced, CQRS ledger	Event sourcing, CQRS, idempotency, optimistic concurrency
settlement-orchestrator	Distributed settlement workflow	SAGA (orchestration), compensation, durable state
strangler-gateway	Routing facade in front of everything	Strangler Fig, weighted/canary routing, ACL boundary

Run it

Tests (no infra required)

mvn test

Full system with Docker

docker compose up --build
# gateway:                 http://localhost:8090
# ledger-service:          http://localhost:8081
# settlement-orchestrator: http://localhost:8082
# legacy-core:             http://localhost:8080

Demo script

./scripts/demo.sh

Walks through: post a payment (CQRS), read the projected balance, run a successful settlement saga, then run a failing settlement that triggers the compensating reversal.

Documentation

• System design + capacity math + SLOs
• Industry applicability
• Business & governance: BRD - SOP - NFR - Cost savings
• Architecture Decision Records: docs/adr/
• Canary / progressive delivery: deploy/k8s/canary/

Tech

Java 21, Spring Boot 3.3, Spring Cloud Gateway, Spring Kafka, JPA/Hibernate, Postgres/H2, Redpanda (Kafka API), Argo Rollouts (canary), Maven multi-module.