High-Volume & Cost-Aware Merchant Payment Platform

Project Overview

This project showcases a conceptual architecture and a set of microservices designed for a high-volume merchant payment platform, with a critical focus on cost-awareness as a first-class architectural principle. Inspired by real-world challenges in banking and financial services, this platform demonstrates how to build systems that are not only technically scalable, performant, and reliable, but also financially sustainable in a cloud-native environment.

Architectural Documentation (arc42)

For a detailed deep-dive into the architecture, including context, solution strategy, building blocks, runtime views, and cross-cutting concerns, please refer to the comprehensive arc42 documentation: arc42 - Merchant Payment Platform

The Problem: Uncontrolled Cloud Costs

In modern cloud-native systems, achieving technical scalability is often a solved problem. However, the hidden challenge that frequently emerges in large enterprises is the uncontrolled escalation of cloud costs. Engineering teams often face scenarios where:

• An API call fans out to numerous downstream services, multiplying costs.
• Aggressive auto-scaling perfectly handles load, but dramatically increases the AWS bill.
• "Free" retry mechanisms generate massive, often unnecessary, compute and network expenses.
• Over-engineered observability pipelines cost more than the systems they monitor.

This showcase addresses these issues by embedding financial intelligence directly into the runtime behavior of the platform.

Core Architectural Principles (Architectural Decision Records - ADRs)

The design of this platform is guided by several key Architectural Decision Records (ADRs), which collectively aim to deliver a robust, scalable, and cost-efficient solution:

1. ADR-001: Adopt Event-Driven Architecture (EDA)

   • Decision: Utilize Kafka for asynchronous communication between payment components.
   • Benefit: Improves scalability, reduces coupling, increases fault isolation, and supports real-time data processing.

2. ADR-002: Design Stateless Services

   • Decision: Implement payment services as stateless components.
   • Benefit: Simplifies horizontal scaling, improves resiliency, and accelerates deployments.

3. ADR-003: Introduce Dead-Letter Processing

   • Decision: Redirect failed events to a Dead Letter Queue (DLQ) for investigation and replay.
   • Benefit: Prevents transaction loss, improves recoverability, and reduces operational risk.

4. ADR-004: Adopt Cost-Aware Architecture

   • Decision: Embed financial intelligence directly into runtime behavior, treating cost as a first-class signal for decision-making.
   • Benefit: Ensures economic sustainability, optimizes resource utilization based on business value, and enables proactive cloud cost management.

Showcase Components

This project will implement the following microservices to demonstrate the architectural principles:

• cost-aware-api-gateway: The entry point for all requests, responsible for initial authentication, routing, and crucially, injecting cost metadata and applying pre-flight cost-based policies (e.g., rate limiting, degradation).
• payment-orchestrator-service: Validates payment requests, consults a Cost Policy Engine to determine the optimal processing path, and initiates the event-driven payment flow via Kafka.
• payment-processor-service: Consumes payment events from Kafka, simulates payment processing, and implements resilient error handling with retries and Dead Letter Queue (DLQ) integration.
• dlq-listener-service: Monitors the DLQ for persistently failed events, logging them for operational investigation and potential replay.

Technology Stack

• Java 21
• Spring Boot 3.2.x
• Spring Cloud Gateway
• Spring Kafka
• Apache Kafka (for event backbone and DLQ)
• Docker / Docker Compose (for local development environment)

How to Run

To run this showcase project locally, follow these steps:

1. Start Infrastructure Services with Docker Compose

Navigate to the root directory of the project (warszawa/) and start Kafka, Zookeeper, and Eureka Server using Docker Compose:

docker-compose up -d

Verify that all containers are running:

docker-compose ps

You should see zookeeper, kafka, and eureka-server in a healthy state.

2. Build All Microservices

From the root directory (warszawa/), build all Spring Boot microservices using Maven:

./mvnw clean install

3. Run Each Microservice

Open separate terminal windows for each microservice. Navigate to their respective directories and run them as Spring Boot applications. Ensure they are started in the following order to allow for proper service registration and topic creation:

a. Run payment-orchestrator-service

cd payment-orchestrator-service
./mvnw spring-boot:run

b. Run payment-processor-service

cd payment-processor-service
./mvnw spring-boot:run

c. Run dlq-listener-service

cd dlq-listener-service
./mvnw spring-boot:run

d. Run cost-aware-api-gateway

cd cost-aware-api-gateway
./mvnw spring-boot:run

Wait for all services to start up and register with the Eureka server (you can check Eureka dashboard at http://localhost:8761).

4. Test the Showcase

Once all services are running, you can send payment requests to the cost-aware-api-gateway.

Example cURL Commands:

a. Successful Payment (Premium Tier, Low Cost):

curl -X POST http://localhost:8080/payments \
-H "Content-Type: application/json" \
-H "X-Customer-Tier: PREMIUM" \
-d '{
  "amount": 50.00,
  "currency": "USD",
  "merchantId": "MERCHANT_001"
}'

Expected: HTTP 202 Accepted. You should see logs in orchestrator and processor services indicating processing.

b. Rejected Payment (Free Tier, High Cost - by Gateway):

curl -X POST http://localhost:8080/payments \
-H "Content-Type: application/json" \
-H "X-Customer-Tier: FREE" \
-d '{
  "amount": 100.00,
  "currency": "USD",
  "merchantId": "MERCHANT_002"
}'

Expected: HTTP 429 Too Many Requests (or similar, depending on mock cost calculation). The gateway should log a rejection.

c. Degraded Payment (Premium Tier, High Cost - by Gateway, still allowed):

curl -X POST http://localhost:8080/payments \
-H "Content-Type: application/json" \
-H "X-Customer-Tier: PREMIUM" \
-d '{
  "amount": 1000.00,
  "currency": "USD",
  "merchantId": "MERCHANT_003"
}'

Expected: HTTP 202 Accepted. The gateway and orchestrator logs should show a "DEGRADED" decision. The processor might simulate longer processing.

d. Rejected Payment (Free Tier, Very High Amount - by Orchestrator):

curl -X POST http://localhost:8080/payments \
-H "Content-Type: application/json" \
-H "X-Customer-Tier: FREE" \
-d '{
  "amount": 1500.00,
  "currency": "USD",
  "merchantId": "MERCHANT_004"
}'

Expected: HTTP 403 Forbidden. The orchestrator should log a rejection.

e. Payment with simulated processing failure (will retry and potentially go to DLQ): Send any valid payment request. Due to the 40% random failure rate in the payment-processor-service, some payments will fail, trigger retries, and eventually land in the dlq-listener-service's logs if retries are exhausted.

Demonstrated Value

This showcase project highlights mastery in:

• Cloud-Native Architecture: Leveraging modern patterns like microservices, event-driven design, and API Gateways.
• FinOps & Cost Management: Proactively addressing cloud cost challenges through architectural design.
• Resilient Systems Design: Implementing robust error handling, retries, and dead-letter processing.
• Scalability & Performance: Designing for high-volume transaction processing.
• Strategic Thinking: Demonstrating an understanding of business impact beyond pure technical implementation.

Disclaimer

This project is a conceptual showcase and a proof-of-concept. It is intended for educational and demonstration purposes only, illustrating architectural patterns and principles. It is not a production-ready payment system and should not be used in real-world financial transactions without significant further development, security hardening, compliance audits, and rigorous testing. The cost models and simulations are simplified for demonstration purposes and do not reflect actual cloud billing or complex financial logic.