A microservices reimagining of the payment-gateway-challenge-java Spring Boot monolith.

This repository is a teaching project, not a production system.

Read the master document first: MICROSERVICES_TEACHING_GUIDE.md. It explains why every choice was made and walks through everything below.

Quick map

Where What
MICROSERVICES_TEACHING_GUIDE.md The textbook. Start here.
docs/01-architecture-decisions.md ADRs explaining each decision.
docs/02-aws-deployment.md End-to-end AWS deployment runbook.
docs/03-cicd.md GitHub Actions pipelines.
docs/04-observability.md Logs, metrics, traces, alerts, SLOs.
services/ The eight microservices.
shared/payment-events/ Wire-level event contract shared by producers/consumers.
infra/ Dockerfiles, docker-compose deps, Terraform IaC.

What's in the box

api-gateway ──► payment-service ─► fraud-check-service
                       │         ─► bank-adapter-service ─► (external bank simulator)
                       │
                       └─► Kafka ─► payment-query-service (read side)
                                 ─► notification-service  (audit + email)
   discovery-server (Eureka) + config-server (Spring Cloud Config)

Run it locally

docker compose up --build

Useful endpoints (after ~60 s for everything to register):

URL What
http://localhost:8080/api/payments Public API (gateway)
http://localhost:8761 Eureka dashboard
http://localhost:8888 Config server
http://localhost:9090 Prometheus
http://localhost:16686 Jaeger UI (traces)

A sample request:

curl -i -X POST http://localhost:8080/api/payments \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: demo-1' \
  -H 'X-Merchant-Id: merchant-acme' \
  -d '{
        "card_number": "2222405343248877",
        "expiry_month": 4,
        "expiry_year": 2030,
        "currency": "GBP",
        "amount": 100,
        "cvv": "123"
      }'

The response includes a Location header pointing at the read side; reads may take up to ~1 s after the write to be visible (eventual consistency).

Build everything from source

./gradlew build

(The Gradle wrapper is shared with the upstream challenge — copy gradlew, gradlew.bat, and the gradle/ directory from ../payment-gateway-challenge-java/ if you do not already have them.)

Deploy to AWS

See docs/02-aws-deployment.md for the full walkthrough.

License

Educational use only.