Enterprise Cloud-Native Payment Switching & Batch Clearing Platform

A mission-critical, enterprise-grade card transaction switching and clearing platform architected according to Digital Network Architecture and Cloud-Native Twelve-Factor principles. Engineered to showcase high-throughput, fault-tolerant patterns powering global card switching networks: dynamic card BIN routing, Stand-In Processing (STIP), Kafka saga choreography, chunk-oriented Spring Batch clearing, and Pivotal Cloud Foundry (PCF) multi-app deployment.

• Overview
• Switching & Core Capabilities
• System Architecture
• Pivotal Cloud Foundry & Cloud Native
• Technology Stack
• Services
• Payment Standards (ISO 8583 & ISO 20022)
• Architecture Patterns
• Getting Started
• API Documentation
• Testing Strategy & Quality Gates
• Observability & SRE
• Documentation Index

MerchantRail is an enterprise payment switching and batch clearing platform that orchestrates the end-to-end card transaction lifecycle: from real-time acquirer switching and issuer authorization to chunked batch clearing and double-entry financial reconciliation.

✅ Card Switching Solutions - Intelligent BIN routing (Mastercard 51-55, 22-27 series, Visa) to multi-issuer endpoints over gRPC (ISO 8583 0100/0110)
✅ Stand-In Processing (STIP) - Autonomous failover authorization evaluating offline limits ($500.00), velocity checks, and risk thresholds when issuer links breach latency SLAs (>2000ms)
✅ Enterprise Spring Batch - Chunk-oriented clearing engine (250 items/chunk) in ledger-service executing daily netting, interchange calculation, and ISO 20022 pain.001 SFTP delivery
✅ Pivotal Cloud Foundry (PCF / Tanzu) - Cloud-native twelve-factor packaging with manifest-pcf.yml, dynamic VCAP_SERVICES bindings, rolling blue-green updates, and autoscaling
✅ Full-Stack Financial Reporting - React + TypeScript reconciliation dashboard with real-time switching analytics, double-entry audit checks, and one-click CSV export
✅ Production Reliability - Outbox pattern, Redis idempotency, balanced double-entry accounting, and 85%+ JaCoCo test coverage

⚡ Card Transaction Switching & Routing

• Real-time authorization routing based on 6-to-8 digit Card BIN
• Dynamic Interchange Fee calculation (1.5% + fixed) and network switch fees
• Multi-issuer endpoint simulation (Citibank, Chase, Barclays, HDFC)
• Sub-50ms switching latency under concurrent traffic

🛡️ Stand-In Processing (STIP)

• Automatic circuit breaker fallback when issuer connectivity degrades or times out
• Evaluates offline velocity, single-transaction limits, and fraud risk thresholds
• Autonomous generation of ST-prefixed authorization codes ensuring zero cardholder drop-off

📦 Spring Batch Clearing & Settlement

• Fault-tolerant chunked execution (commit intervals of 250 records)
• Double-entry bookkeeping balance integrity enforcement (Debit == Credit)
• Automated ISO 20022 XML batch compilation and SFTP upload
• On-demand and scheduled execution monitored via Spring Batch REST APIs

📊 Full-Stack Financial Reporting & Analytics

• Real-time network throughput and card brand market share analytics
• STIP authorization rate tracking and issuer latency percentiles
• Interactive double-entry reconciliation ledger table with status filtering
• Direct CSV export for automated compliance audits

🛡️ Fraud Detection

• Rule-based engine with velocity checks
• Real-time analysis (<100ms evaluation)
• Configurable rules with Spock tests
• Historical pattern analysis

💰 Financial Management

• Double-entry bookkeeping (balanced ledger)
• Automated nightly settlement (ISO 20022)
• SFTP file delivery
• Complete audit trail via event sourcing

🔐 Security & Compliance

• JWT authentication with RBAC (MERCHANT, ADMIN, BANK)
• API key management
• Rate limiting (20 req/sec per IP)
• OWASP ZAP + Dependency-Check scanning
• Complete event log for compliance

🚀 Operational Excellence

• Zero-downtime deployments with canary releases
• Prometheus metrics + Grafana dashboards
• Distributed tracing across all services
• Chaos engineering with Toxiproxy
• Kubernetes-ready architecture

8 Independent Services - Each service has its own database, can be deployed independently, and communicates via well-defined interfaces.

Event-Driven Choreography - Services coordinate through Kafka events using the saga pattern, eliminating single points of failure.

Database-Per-Service - Complete data isolation with no direct database access across services.

Zero Framework Coupling - Domain layer is pure Java with no Spring annotations or framework dependencies.

Ports & Adapters - Clear separation between business logic and infrastructure concerns.

Testable Without Infrastructure - Business logic can be tested with simple mocks, no database or messaging required.

Submit → Idempotency Check → Fraud Analysis → Bank Authorization → 
Ledger Entry → Settlement File Generation → SFTP Delivery

Each step is asynchronous, resilient to failures, and fully traceable.

Outbox Pattern - Transactional event publishing ensures at-least-once delivery.

Idempotency Pattern - Redis-based tracking prevents duplicate charges on network retries.

Saga Pattern - Distributed transaction coordination with automatic compensation on failures.

Circuit Breaker - Prevents cascading failures when downstream services are unavailable.

ISO 8583 - Standard format for bank authorization messages via gRPC.

ISO 20022 (pain.001) - XML settlement file format for credit transfers.

Double-Entry Bookkeeping - Every transaction creates balanced debit/credit entries.

Unit Tests - 80+ tests with JUnit 5 and Mockito (>90% coverage).

BDD Tests - 12+ Spock specifications with data-driven testing.

Integration Tests - 15+ tests with Testcontainers using real Postgres, Kafka, and Redis.

Chaos Tests - Network failure injection with Toxiproxy to validate saga compensation.

Security Tests - OWASP ZAP dynamic scanning + Dependency-Check for CVEs.

┌─────────────────────────────────────────────────────────────────────┐
│                          API Gateway :8080                           │
│            (Rate Limiting, Routing, Authentication)                  │
└──────────────────────┬──────────────────────────────────────────────┘
                       │
         ┌─────────────┼─────────────────┐
         │             │                 │
    ┌────▼────┐   ┌────▼─────┐     ┌────▼────────┐
    │  Auth   │   │ Merchant │     │ Transaction │◄──── WebSocket
    │ Service │   │ Service  │     │   Service   │      (Real-time)
    │  :8086  │   │  :8083   │     │    :8081    │
    └─────────┘   └──────────┘     └──────┬──────┘
                                          │
                                    Kafka Event Bus
                    ┌────────────────────┼──────────────────┐
                    │                    │                  │
              ┌─────▼──────┐      ┌─────▼─────┐     ┌─────▼────────┐
              │   Fraud    │      │   Bank    │     │ Notification │
              │  Service   │      │ Simulator │     │   Service    │
              │   :8082    │      │   :9090   │     │    :8087     │
              └─────┬──────┘      └─────┬─────┘     └──────────────┘
                    │                   │
                    └────────┬──────────┘
                             │
                       ┌─────▼──────┐
                       │   Ledger   │ ───SFTP───> [Settlement Files]
                       │  Service   │              pain.001.xml
                       │   :8085    │
                       └────────────┘

Infrastructure Layer:
┌──────────┐  ┌────────┐  ┌───────┐  ┌────────────┐  ┌─────────┐
│PostgreSQL│  │ Kafka  │  │ Redis │  │ Prometheus │  │ Grafana │
│  :5432   │  │ :9092  │  │ :6379 │  │   :9090    │  │  :3000  │
└──────────┘  └────────┘  └───────┘  └────────────┘  └─────────┘

Complete Payment Lifecycle:

1. Merchant submits transaction → API Gateway (rate limit check)
2. Transaction Service saves to database + idempotency check (Redis)
3. Publishes transaction.initiated event → Kafka
4. Fraud Service consumes event → evaluates rules → publishes fraud.passed/failed
5. Transaction Service consumes result → calls Bank Simulator via gRPC (ISO 8583)
6. Bank responds with approval/decline → publishes transaction.approved/declined
7. Ledger Service consumes event → creates double-entry bookkeeping entries
8. Notification Service sends webhook to merchant
9. Nightly Job: Ledger generates ISO 20022 XML → uploads via SFTP

Compensation Flow (on failure):

• If bank declines or times out → transaction.reversed event published
• Ledger Service creates compensating entries (reversal)
• Merchant notified of failure

🎯 Real-time Transaction Monitoring

• Live transaction feed with WebSocket updates
• Interactive charts (Recharts): trends, status distribution, merchant analytics
• Transaction search, filter, and pagination
• Detailed transaction view with full audit trail

💼 Merchant Portal

• Transaction history and statistics
• API key management
• Success rate and volume metrics
• Responsive mobile-first design (Tailwind CSS)

⚡ Technical Highlights

• React 18 with TypeScript for type safety
• React Query for efficient API data fetching
• Socket.io for real-time WebSocket connection
• Tailwind CSS for modern, responsive UI
• Dockerized with nginx for production deployment

REST/HTTPS    → Client ↔ API Gateway, inter-service queries, Frontend ↔ Backend
gRPC          → transaction-service ↔ bank-simulator (high-performance RPC)
Kafka Events  → Asynchronous saga choreography (all services)
WebSocket     → Real-time transaction status updates (transaction-service ↔ frontend)
SFTP          → Settlement file delivery (ledger-service → bank)

Example: transaction-service

transaction-service/
├── domain/                    # Pure business logic (ZERO framework dependencies)
│   ├── Transaction.java       # Entity with state machine
│   ├── TransactionStatus.java # Enum (PENDING, APPROVED, SETTLED, REVERSED)
│   └── Money.java             # Value object
├── application/               # Use cases (no infrastructure)
│   ├── port/
│   │   ├── in/               # Input ports (SubmitTransactionCommand)
│   │   └── out/              # Output ports (TransactionRepository, EventPublisher)
│   └── usecase/
│       ├── SubmitTransactionUseCase.java
│       └── GetTransactionUseCase.java
├── adapter/                   # Framework implementations
│   ├── in/
│   │   ├── web/              # REST controllers
│   │   └── messaging/        # Kafka consumers
│   ├── out/
│   │   ├── persistence/      # JPA repositories
│   │   ├── messaging/        # Kafka producers
│   │   ├── client/           # gRPC clients
│   │   └── cache/            # Redis idempotency
│   └── config/               # Spring configuration
└── infrastructure/            # Main application, config files

Benefits:

• Domain logic testable without Spring/database
• Can swap JPA for MongoDB without touching business logic
• Clear boundaries between layers
• Framework details isolated in adapters

Purpose: Standard format for electronic transaction messages between transaction service and issuing bank.

Implementation: gRPC service definition in bank-simulator-service.

Message Structure:

message AuthorizationRequest {
  string mti = 1;              // Message Type Indicator (0100 = auth request)
  string pan = 2;              // Primary Account Number (masked: 4111****1111)
  int64 amount = 3;            // Amount in minor units (cents)
  string currency = 4;         // ISO 4217 code (USD, EUR, GBP)
  string merchant_id = 5;
  string transaction_id = 6;
}

message AuthorizationResponse {
  string mti = 1;              // 0110 = auth response
  string response_code = 2;    // 00=approved, 05=declined, 51=insufficient funds
  string authorization_code = 3; // 6-character approval code
}

Response Codes:

• 00 - Approved
• 05 - Declined (do not honor)
• 51 - Insufficient funds
• 91 - Issuer or switch inoperative (timeout)
• 96 - System malfunction

Purpose: XML-based standard for credit transfer initiation messages.

Implementation: ledger-service generates nightly settlement files.

XML Structure:

<Document xmlns="urn:iso:std:iso:20022:tech:xsd:pain.001.001.03">
  <CstmrCdtTrfInitn>
    <GrpHdr>
      <MsgId>SETTLEMENT-20260720</MsgId>
      <CreDtTm>2026-07-20T02:00:00Z</CreDtTm>
      <NbOfTxs>150</NbOfTxs>
      <CtrlSum>45000.00</CtrlSum>
    </GrpHdr>
    <PmtInf>
      <PmtInfId>BATCH-001</PmtInfId>
      <PmtMtd>TRF</PmtMtd>
      <CdtTrfTxInf>
        <Amt Ccy="USD">10000</Amt>
        <CdtrAcct>
          <Id><IBAN>US1234567890</IBAN></Id>
        </CdtrAcct>
      </CdtTrfTxInf>
    </PmtInf>
  </CstmrCdtTrfInitn>
</Document>

Delivery: Uploaded to bank SFTP server nightly at 2:00 AM.

Principle: Every transaction affects at least two accounts; total debits must equal total credits.

Example Transaction: $100 from Customer to Merchant (2% platform fee)

Ledger Entries:
1. Debit  - Customer Account:     $100.00
2. Credit - Merchant Account:      $98.00
3. Debit  - Merchant Account:       $2.00  (fee)
4. Credit - Platform Account:       $2.00  (fee)

Verification: $100.00 (debit) = $100.00 (credit) ✓

Benefits:

• Self-balancing system (errors detected automatically)
• Complete audit trail
• Supports reconciliation and financial reporting
• Industry standard for all financial systems

Domain Layer - Pure Java, zero framework dependencies

public class Transaction {
    private TransactionId id;
    private Money amount;
    private TransactionStatus status;
    
    public void approve() {
        if (status != TransactionStatus.PENDING) {
            throw new IllegalStateException("Can only approve pending transactions");
        }
        this.status = TransactionStatus.APPROVED;
    }
}

Application Layer - Use cases with port interfaces

public class SubmitTransactionUseCase {
    private final TransactionRepository repository;  // Port (interface)
    private final EventPublisher publisher;          // Port (interface)
    
    public Transaction execute(SubmitTransactionCommand cmd) {
        // Business logic here
    }
}

Adapter Layer - Framework implementations

@Repository
public class JpaTransactionRepository implements TransactionRepository {
    // JPA implementation
}

Event-Driven Coordination - No central orchestrator

transaction.initiated
  ↓ consumed by fraud-service
fraud.passed
  ↓ consumed by transaction-service
transaction.approved
  ↓ consumed by ledger-service
ledger.recorded
  ↓ consumed by notification-service
webhook sent to merchant

Compensation on Failure:

bank.declined OR bank.timeout
  ↓
transaction.reversed (published)
  ↓ consumed by ledger-service
compensating ledger entries created (reversal)
  ↓ consumed by notification-service
merchant notified of reversal

Problem: How to atomically update database AND publish Kafka event?

Solution: Write event to database outbox table in same transaction, then publish asynchronously.

@Transactional
public Transaction submitTransaction(Command cmd) {
    Transaction txn = repository.save(transaction);
    outboxRepository.save(new OutboxEvent("transaction.initiated", txn));
    return txn; // Commit both in same transaction
}

@Scheduled(fixedDelay = 1000)
public void publishOutboxEvents() {
    List<OutboxEvent> unpublished = outboxRepository.findUnpublished();
    unpublished.forEach(event -> {
        kafkaProducer.send(event.getTopic(), event.getPayload());
        event.markAsPublished();
        outboxRepository.save(event);
    });
}

Guarantees: At-least-once delivery, no message loss even if Kafka is down.

Problem: Network retries can cause duplicate transactions.

Solution: Redis-based idempotency key tracking (24-hour TTL).

public Transaction submitTransaction(Command cmd) {
    String key = "idempotency:" + cmd.getIdempotencyKey();
    
    // Check if already processed
    String existingTxnId = redisTemplate.opsForValue().get(key);
    if (existingTxnId != null) {
        return repository.findById(existingTxnId); // Return existing
    }
    
    // Process new transaction
    Transaction txn = repository.save(new Transaction(cmd));
    
    // Store idempotency mapping (24h TTL)
    redisTemplate.opsForValue().set(key, txn.getId(), 24, TimeUnit.HOURS);
    
    return txn;
}

Critical for payments: Prevents duplicate charges on network failures/retries.

Each service owns its database:

transaction-service → transaction_db (PostgreSQL)
fraud-service       → fraud_db (PostgreSQL)
ledger-service      → ledger_db (PostgreSQL)
merchant-service    → merchant_db (PostgreSQL)
auth-service        → auth_db (PostgreSQL)

Benefits:

• Service independence (can deploy/scale independently)
• Schema evolution without coordination
• Technology polyglotism (can use different databases)
• Clear ownership boundaries

Tradeoffs:

• No distributed ACID transactions (hence saga pattern)
• Eventual consistency
• Some data duplication (denormalization)

For Frontend Development:

Verify Installation:

java -version    # Should show Java 17+
mvn --version    # Should show Maven 3.8+
docker --version # Should show Docker 20+
docker compose version
git --version

📖 Detailed setup guide: docs/setup/prerequisites.md

git clone https://github.com/maheshsingh20/merchantrail.git
cd merchantrail

docker-compose up -d

This starts:

• PostgreSQL (port 5432)
• Kafka (port 9092)
• Redis (port 6379)
• Prometheus (port 9090)
• Grafana (port 3000)

Wait for health checks (~30 seconds):

docker-compose ps
# All services should show "healthy"

mvn clean install

Build time: ~2-3 minutes (downloads dependencies, runs tests)

Option A: Docker Compose (Recommended - includes frontend):

docker-compose up -d

Access:

• Frontend Dashboard: http://localhost:3000
• API Gateway: http://localhost:8080
• Transaction Service: http://localhost:8081
• Prometheus: http://localhost:9090
• Grafana: http://localhost:3000 (Note: port conflict with frontend in dev)

Option B: Run All 8 Services + Frontend (9 terminals):

# Backend Services (Terminals 1-8)
cd api-gateway && mvn spring-boot:run
cd auth-service && mvn spring-boot:run
cd merchant-service && mvn spring-boot:run
cd transaction-service && mvn spring-boot:run
cd fraud-service && mvn spring-boot:run
cd bank-simulator-service && mvn spring-boot:run
cd ledger-service && mvn spring-boot:run
cd notification-service && mvn spring-boot:run

# Frontend (Terminal 9)
cd frontend && npm install && npm start

Option C: Run Core Services Only (4 terminals - minimal setup):

cd transaction-service && mvn spring-boot:run      # Core
cd fraud-service && mvn spring-boot:run            # Fraud detection
cd bank-simulator-service && mvn spring-boot:run   # Bank
cd frontend && npm install && npm start            # Dashboard

Wait for startup: Each service takes ~10-15 seconds. Look for:

Started Application in X seconds

Frontend will be available at: http://localhost:3000

Via Frontend Dashboard:

1. Open http://localhost:3000
2. View real-time transaction feed
3. Browse transaction history
4. Monitor system statistics

Via API:

Submit a Transaction:

curl -X POST http://localhost:8081/api/v1/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "MERCH001",
    "amount": 100.50,
    "currency": "USD",
    "idempotencyKey": "test-key-123"
  }'

Expected Response (201 Created):

{
  "transactionId": "TXN1234567890ABC",
  "merchantId": "MERCH001",
  "amount": 100.50,
  "currency": "USD",
  "status": "PENDING",
  "createdAt": "2026-07-20T10:30:00Z",
  "updatedAt": "2026-07-20T10:30:00Z"
}

Get Transaction Status:

curl http://localhost:8081/api/v1/transactions/TXN1234567890ABC

Watch Status Change (over a few seconds):

PENDING → FRAUD_CHECK → APPROVED → SETTLED

Test Idempotency (duplicate submission):

# Submit same request again with same idempotencyKey
curl -X POST http://localhost:8081/api/v1/transactions \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "MERCH001",
    "amount": 100.50,
    "currency": "USD",
    "idempotencyKey": "test-key-123"
  }'

Result: Returns same transaction (same transactionId) - no duplicate created! ✅

List Merchant Transactions:

curl "http://localhost:8081/api/v1/transactions?merchantId=MERCH001"

Sample Prometheus Queries:

# Request rate
rate(http_server_requests_seconds_count[1m])

# Error rate
rate(http_server_requests_seconds_count{status="5xx"}[1m])

# p95 latency
histogram_quantile(0.95, http_server_requests_seconds_bucket)

# Unit tests only (fast - <30 seconds)
mvn test

# Unit + integration tests (~2 minutes, requires Docker)
mvn verify

# Test specific service
cd transaction-service
mvn test

# Test with coverage report
mvn clean verify
# Open target/site/jacoco/index.html

# Stop application services
# Press Ctrl+C in each terminal

# Stop infrastructure
docker-compose down

# Clean everything (including data volumes)
docker-compose down -v

⚠️ Warning: docker-compose down -v deletes all database data and Kafka topics.

📖 Detailed guide: QUICK_START.md

POST /api/v1/transactions
Content-Type: application/json

{
  "merchantId": "MERCH001",
  "amount": 100.50,
  "currency": "USD",
  "idempotencyKey": "unique-key-123"
}

Validation Rules:

• merchantId: Required, 8 alphanumeric characters
• amount: Required, 0.01 to 1,000,000
• currency: Required, ISO 4217 code (USD, EUR, GBP, JPY, etc.)
• idempotencyKey: Required, max 255 characters, unique per merchant

Response (201 Created):

{
  "transactionId": "TXN1234567890ABC",
  "merchantId": "MERCH001",
  "amount": 100.50,
  "currency": "USD",
  "status": "PENDING",
  "createdAt": "2026-07-20T10:30:00Z",
  "updatedAt": "2026-07-20T10:30:00Z"
}

Status Codes:

• 201 Created - Transaction submitted successfully
• 400 Bad Request - Validation error (invalid merchantId, amount, currency)
• 409 Conflict - Duplicate idempotency key
• 429 Too Many Requests - Rate limit exceeded (>20 req/sec)
• 500 Internal Server Error - System error

GET /api/v1/transactions/{transactionId}

Response (200 OK):

{
  "transactionId": "TXN1234567890ABC",
  "merchantId": "MERCH001",
  "amount": 100.50,
  "currency": "USD",
  "status": "APPROVED",
  "createdAt": "2026-07-20T10:30:00Z",
  "updatedAt": "2026-07-20T10:30:15Z"
}

Transaction Status Values:

• PENDING - Initial state after submission
• FRAUD_CHECK - Under fraud evaluation
• APPROVED - Passed fraud check and bank authorization
• REJECTED - Declined by fraud service or bank
• SETTLED - Included in settlement batch
• REVERSED - Compensating transaction (chargeback/refund)

GET /api/v1/transactions?merchantId={merchantId}&page=0&size=20&sort=createdAt,desc

Query Parameters:

• merchantId: Required, filter by merchant
• page: Optional, page number (default: 0)
• size: Optional, page size (default: 20, max: 100)
• sort: Optional, sort field and direction (default: createdAt,desc)

Response (200 OK):

{
  "content": [
    {
      "transactionId": "TXN1234567890ABC",
      "amount": 100.50,
      "currency": "USD",
      "status": "APPROVED",
      "createdAt": "2026-07-20T10:30:00Z"
    }
  ],
  "page": 0,
  "size": 20,
  "totalElements": 1,
  "totalPages": 1
}

Connect to Transaction Updates:

const socket = new WebSocket('ws://localhost:8081/ws/transactions/TXN1234567890ABC');

socket.onopen = () => {
  console.log('Connected to transaction updates');
};

socket.onmessage = (event) => {
  const update = JSON.parse(event.data);
  console.log('Transaction status:', update.status);
  console.log('Timestamp:', update.timestamp);
};

socket.onerror = (error) => {
  console.error('WebSocket error:', error);
};

socket.onclose = () => {
  console.log('Connection closed');
};

Message Format:

{
  "transactionId": "TXN1234567890ABC",
  "status": "APPROVED",
  "timestamp": "2026-07-20T10:30:15Z"
}

Service Definition (bank_authorization.proto):

service BankAuthorizationService {
  rpc Authorize (AuthorizationRequest) returns (AuthorizationResponse);
}

Usage from transaction-service:

AuthorizationRequest request = AuthorizationRequest.newBuilder()
    .setMti("0100")
    .setPan("4111****1111")
    .setAmount(10000)  // $100.00 in cents
    .setCurrency("USD")
    .setMerchantId("MERCH001")
    .setTransactionId("TXN1234567890ABC")
    .build();

AuthorizationResponse response = bankStub.authorize(request);

if ("00".equals(response.getResponseCode())) {
    // Approved
} else {
    // Declined
}

            ┌─────────┐
            │Security │  OWASP ZAP, Dependency-Check
            └─────────┘
          ┌─────────────┐
          │ Chaos & Load│  Toxiproxy, Gatling
          └─────────────┘
        ┌─────────────────┐
        │   E2E & Protocol│  REST Assured, gRPC, SFTP
        └─────────────────┘
      ┌─────────────────────┐
      │   Integration Tests │  Testcontainers (real infra)
      └─────────────────────┘
  ┌───────────────────────────┐
  │      Unit Tests           │  JUnit 5, Spock, Mockito
  │  (Domain & Application)   │  Fast, isolated, >80% coverage
  └───────────────────────────┘

✅ Fast Feedback - Unit tests complete in seconds
✅ Real Infrastructure - Testcontainers uses actual Postgres/Kafka/Redis (not H2/mocks)
✅ No Mocks in Integration - Test real adapter implementations
✅ Chaos Engineering - Validates saga compensation, circuit breakers, resilience patterns
✅ Performance Validation - Gatling load tests with 500+ concurrent users
✅ Contract Testing - Spring Cloud Contract ensures API compatibility
✅ Protocol Coverage - All integration protocols tested (REST, gRPC, WebSocket, SFTP)
✅ Coverage Enforcement - JaCoCo enforces >80% on business logic

Unit Test (Domain Layer):

@Test
void shouldTransitionFromPendingToApproved() {
    Transaction txn = Transaction.create(merchantId, money, idempotencyKey);
    
    txn.approve();
    
    assertThat(txn.getStatus()).isEqualTo(TransactionStatus.APPROVED);
    assertThat(txn.getUpdatedAt()).isAfter(txn.getCreatedAt());
}

Spock Test (Data-Driven):

def "fraud score calculation for various patterns"() {
    given:
    def transaction = new Transaction(amount, merchantId)
    
    when:
    def score = fraudEngine.calculateScore(transaction)
    
    then:
    score == expectedScore
    
    where:
    amount | merchantId || expectedScore
    100    | "M001"     || 10   // Normal transaction
    10000  | "M001"     || 75   // High amount
    100    | "M999"     || 50   // New merchant
}

Integration Test (Testcontainers):

@Testcontainers
@SpringBootTest
class TransactionRepositoryIT {
    
    @Container
    static PostgreSQLContainer<?> postgres = 
        new PostgreSQLContainer<>("postgres:15");
    
    @Test
    void shouldSaveAndRetrieveTransaction() {
        Transaction saved = repository.save(transaction);
        
        Transaction retrieved = repository.findById(saved.getId()).orElseThrow();
        
        assertThat(retrieved.getAmount()).isEqualTo(saved.getAmount());
    }
}

Chaos Test (Toxiproxy):

@Test
void whenBankTimesOut_sagaReversesTransaction() {
    // Inject 10s latency to bank simulator
    toxiproxy.toxics()
        .latency("bank-timeout", ToxicDirection.DOWNSTREAM, 10_000);
    
    String txnId = submitTransaction();
    
    // Assert transaction moves to REVERSED status
    await().atMost(15, SECONDS)
        .until(() -> getTransactionStatus(txnId).equals("REVERSED"));
    
    // Assert compensating ledger entries created
    List<LedgerEntry> entries = ledgerRepository.findByTransactionId(txnId);
    assertEquals(4, entries.size()); // 2 original + 2 reversal
}

Load Test (Gatling):

class TransactionLoadSimulation extends Simulation {
  
  val httpProtocol = http.baseUrl("http://localhost:8081")
  
  val scn = scenario("Submit Transactions")
    .exec(http("Submit Transaction")
      .post("/api/v1/transactions")
      .body(StringBody("""{ "merchantId": "M123", "amount": 99.99 }"""))
      .check(status.is(201)))
  
  setUp(
    scn.inject(
      rampUsers(500).during(60.seconds)  // Ramp to 500 concurrent users
    )
  ).protocols(httpProtocol)
   .assertions(
     global.responseTime.percentile(95).lt(500),  // p95 < 500ms
     global.successfulRequests.percent.gt(99)     // >99% success
   )
}

Contract Test (Spring Cloud Contract):

Contract.make {
    description "Should accept a valid transaction submission"
    
    request {
        method POST()
        url "/api/v1/transactions"
        body([
            merchantId: "MERCHANT_12345",
            amount: 99.99,
            currency: "USD"
        ])
    }
    
    response {
        status 201
        body([
            transactionId: $(consumer(~/.+/), producer("TX_123")),
            status: "PENDING"
        ])
    }
}

# Run all tests
mvn clean verify

# Run specific test categories
mvn test                                    # Unit tests only
mvn verify -Dtest=*IT                       # Integration tests
mvn verify -Dtest=*ChaosTest                # Chaos tests
mvn gatling:test                            # Load tests
mvn verify -Dtest=ContractTest              # Contract tests

# Run with coverage
mvn verify jacoco:report

# Run security scans
mvn dependency-check:check                  # Dependency vulnerabilities
docker run -t owasp/zap2docker-stable zap-api-scan.py -t http://localhost:8081/api

📖 Comprehensive testing guide: TEST_STRATEGY.md

All services expose Prometheus metrics at /actuator/prometheus.

Key Metrics:

# Request rate (requests per second)
rate(http_server_requests_seconds_count[1m])

# Error rate (5xx responses)
rate(http_server_requests_seconds_count{status="5xx"}[1m])

# p95 latency (95th percentile response time)
histogram_quantile(0.95, http_server_requests_seconds_bucket)

# Kafka consumer lag
kafka_consumer_lag{topic="transaction.initiated"}

# Transaction status distribution
transaction_status_total{status="APPROVED"}
transaction_status_total{status="REJECTED"}

Access: http://localhost:3000 (admin/admin)

Pre-configured Dashboards:

1. Transaction Service Overview

   • Request rate, latency, error rate
   • Transaction status distribution
   • Active transactions

2. Kafka Metrics

   • Message throughput
   • Consumer lag
   • Topic partition metrics

3. JVM & System Metrics

   • Heap memory usage
   • GC activity
   • Thread count
   • CPU usage

All services expose health endpoints:

# Transaction Service
curl http://localhost:8081/actuator/health

# Response
{
  "status": "UP",
  "components": {
    "db": {"status": "UP"},
    "kafka": {"status": "UP"},
    "redis": {"status": "UP"}
  }
}

Trace ID Propagation: All services propagate trace IDs via headers.

Log Format:

2026-07-20 10:30:00.123 INFO [transaction-service,abc123,def456] 
  Transaction TXN1234567890ABC submitted

• abc123 - Trace ID (same across all services for a request)
• def456 - Span ID (unique per service)

✅ Authentication & Authorization

• JWT-based authentication with role-based access control
• Three roles: MERCHANT (submit transactions), ADMIN (full access), BANK (bank operations)
• API key authentication for merchant API access
• Token expiration and refresh mechanism

✅ API Protection

• Rate limiting at API Gateway (20 requests/second per IP)
• Request validation with Bean Validation (@Valid)
• SQL injection prevention via JPA parameterized queries
• XSS prevention with input sanitization

✅ Security Scanning (CI/CD)

• OWASP Dependency-Check for CVE scanning
• OWASP ZAP baseline scan for vulnerabilities
• Automated security gates in pipeline

✅ Audit Trail

• Complete event log via Kafka (7-day retention)
• All transactions logged with timestamps
• Immutable event history for compliance

OWASP Dependency-Check:

mvn org.owasp:dependency-check-maven:check
# Scans dependencies for known CVEs
# Report: target/dependency-check-report.html

OWASP ZAP Baseline Scan:

docker run -v $(pwd):/zap/wrk:rw owasp/zap2docker-stable \
  zap-baseline.py -t http://localhost:8081 -r zap-report.html

Security Checklist:

• No hardcoded credentials (all externalized)
• HTTPS-ready (TLS configuration available)
• Input validation on all endpoints
• Parameterized database queries (no string concatenation)
• JWT token validation
• Rate limiting enabled
• Security headers configured
• Audit logging enabled

📖 Detailed security guide: docs/SECURITY_TESTING.md

Trigger: Every push to main, every pull request

Stages:

1. Lint & Static Analysis
   - Checkstyle/SpotBugs
   - Code formatting validation

2. Unit Tests
   - JUnit 5 + Spock tests
   - Fast feedback (<30 seconds)

3. Build
   - Maven package
   - Docker image build

4. Integration Tests
   - Testcontainers (Postgres, Kafka, Redis)
   - Full adapter layer testing

5. Code Coverage Gate
   - JaCoCo >80% enforcement
   - Report generation

6. Security Scans
   - OWASP Dependency-Check
   - OWASP ZAP baseline scan

7. Deploy (optional)
   - Docker image push
   - Kubernetes deployment

Canary Deployment (Progressive Delivery):

Step 1: Deploy to 10% of instances
        → Run smoke tests
        → Monitor metrics for 5 minutes

Step 2: If healthy, deploy to 50%
        → Monitor for 5 minutes

Step 3: If healthy, deploy to 100%
        → Complete rollout

On any failure: Automatic rollback to previous version

Health Metrics for Deployment:

• Error rate < 1%
• p95 latency < 500ms
• All health checks passing
• No increase in Kafka consumer lag

Smoke Tests:

#!/bin/bash
# Submit test transaction
response=$(curl -X POST http://transaction-service:8081/api/v1/transactions \
  -H "Content-Type: application/json" \
  -d '{"merchantId":"TEST001","amount":1,"currency":"USD","idempotencyKey":"smoke"}')

# Verify response contains transactionId
if echo "$response" | grep -q "transactionId"; then
  echo "✅ Smoke test PASSED"
  exit 0
else
  echo "❌ Smoke test FAILED"
  exit 1
fi

📖 Detailed CI/CD guide: docs/ARA_STRATEGY.md

merchantrail/
├── .github/
│   └── workflows/
│       └── ci.yml                 # GitHub Actions CI/CD pipeline
├── shared-kernel/                 # Shared value objects
│   └── src/main/java/
│       └── dev/merchantrail/shared/
│           ├── Money.java         # Value object with currency
│           ├── TransactionId.java # 16-char alphanumeric ID
│           └── MerchantId.java    # 8-char alphanumeric ID
├── api-gateway/                   # Spring Cloud Gateway
│   └── src/main/resources/
│       └── application.yml        # Routing & rate limiting config
├── auth-service/                  # JWT authentication
│   └── src/main/java/
│       └── dev/merchantrail/auth/
├── merchant-service/              # Merchant management
│   └── src/main/java/
│       └── dev/merchantrail/merchant/
├── transaction-service/           # ⭐ Core orchestration service
│   ├── src/main/java/
│   │   └── dev/merchantrail/transaction/
│   │       ├── domain/            # Pure business logic
│   │       │   ├── Transaction.java
│   │       │   ├── TransactionStatus.java
│   │       │   └── Money.java
│   │       ├── application/       # Use cases
│   │       │   ├── port/in/       # Commands, queries
│   │       │   ├── port/out/      # Repository, messaging
│   │       │   └── usecase/
│   │       └── adapter/           # Framework implementations
│   │           ├── in/web/        # REST controllers
│   │           ├── in/messaging/  # Kafka consumers
│   │           ├── out/persistence/ # JPA repositories
│   │           ├── out/messaging/ # Kafka producers
│   │           ├── out/client/    # gRPC clients
│   │           └── out/cache/     # Redis idempotency
│   └── src/test/java/             # Unit & integration tests
├── fraud-service/                 # Rule-based fraud detection
│   ├── src/main/java/
│   │   └── dev/merchantrail/fraud/
│   │       ├── domain/
│   │       │   ├── FraudRule.java
│   │       │   └── FraudCheckResult.java
│   │       └── application/
│   └── src/test/groovy/           # Spock tests
│       └── dev/merchantrail/fraud/
│           └── FraudRuleSpec.groovy
├── bank-simulator-service/        # ISO 8583 bank simulator
│   ├── src/main/proto/
│   │   └── bank_authorization.proto # gRPC service definition
│   └── src/main/java/
│       └── dev/merchantrail/bank/
├── ledger-service/                # Double-entry bookkeeping
│   └── src/main/java/
│       └── dev/merchantrail/ledger/
│           ├── domain/
│           │   └── LedgerEntry.java
│           └── settlement/
│               └── ISO20022Generator.java # Settlement file generator
├── notification-service/          # Webhook callbacks
│   └── src/main/java/
│       └── dev/merchantrail/notification/
├── infrastructure/
│   ├── prometheus/
│   │   └── prometheus.yml         # Metrics scraping config
│   └── grafana/
│       ├── dashboards/            # Pre-configured dashboards
│       └── datasources/           # Prometheus datasource
├── docs/
│   ├── sprints/
│   │   └── sprint-1.md            # Sprint planning & tracking
│   ├── setup/
│   │   └── prerequisites.md       # Setup instructions
│   ├── ARA_STRATEGY.md            # CI/CD strategy
│   └── SECURITY_TESTING.md        # Security testing guide
├── docker-compose.yml             # Local infrastructure
├── pom.xml                        # Parent POM with dependency versions
├── README.md                      # This file
├── PROJECT_COMPLETE.md            # ⭐ Complete project overview
├── TEST_STRATEGY.md               # Comprehensive testing guide
├── QUICK_START.md                 # Quick start guide
└── .gitignore

Architecture Diagrams: See PROJECT_COMPLETE.md for sequence diagrams and data flow charts.

API Examples: Full curl examples in API Documentation section.

Testing Examples: See TEST_STRATEGY.md for test code snippets.

• Shared Kernel - Money, TransactionId, MerchantId value objects
• Transaction Service - Clean architecture, idempotency, saga coordinator
• Fraud Service - Rule-based detection with Spock tests
• Bank Simulator - gRPC service with ISO 8583 format
• Ledger Service - Double-entry bookkeeping, ISO 20022 settlement
• Merchant Service - Onboarding, API key management
• Auth Service - JWT authentication with RBAC
• Notification Service - Webhook callbacks with retry logic
• API Gateway - Rate limiting, routing, authentication
• Event-Driven Architecture - Kafka saga pattern with compensation
• Outbox Pattern - Reliable event publishing
• Testing Infrastructure - Unit, integration, chaos tests
• CI/CD Pipeline - GitHub Actions with security scans
• Observability - Prometheus + Grafana
• Documentation - 7 comprehensive guides

Phase 5: Advanced Testing ✅ COMPLETED

• Chaos Engineering - Toxiproxy tests (database latency, Redis partition, Kafka failures)
• Saga Compensation - Chaos validation of distributed transaction rollback
• Circuit Breaker - Resilience4j chaos testing under failure scenarios
• Load Testing - Gatling simulations (500+ concurrent users, spike tests)
• Contract Testing - Spring Cloud Contract (REST API contracts)
• E2E Protocol Tests - REST, gRPC, WebSocket, SFTP validation

Phase 6: Frontend Dashboard ✅ COMPLETED

• React + TypeScript - Modern frontend with type safety
• Real-time Dashboard - Transaction monitoring with live updates
• WebSocket Integration - Socket.io for real-time transaction feeds
• Interactive Charts - Recharts visualizations (trends, status distribution)
• Transaction Management - List, filter, search with pagination
• Responsive UI - Tailwind CSS mobile-first design
• Docker Configuration - Multi-stage build with nginx
• Production Ready - Health checks, API proxy, security headers

Phase 7: Production Infrastructure

• Kubernetes manifests with Helm charts
• Service mesh integration (Istio)
• Multi-region deployment configuration
• Advanced distributed tracing (Jaeger/Zipkin)
• Mutation testing with PIT

Contributions, issues, and feature requests are welcome!

1. Fork the repository
2. Create a feature branch

   git checkout -b feature/amazing-feature

3. Make your changes
4. Commit your changes (use Conventional Commits format)

   git commit -m 'feat: add amazing feature'
   git commit -m 'fix: resolve transaction status bug'
   git commit -m 'docs: update API documentation'

5. Push to the branch

   git push origin feature/amazing-feature

6. Open a Pull Request

Code Quality:

• Follow Clean Code principles
• Maintain >80% test coverage for domain/application layers
• Write self-documenting code with clear variable names
• Keep methods small and focused (Single Responsibility Principle)

Testing:

• Write unit tests for all business logic
• Add integration tests for adapter implementations
• Update test documentation if adding new test patterns

Documentation:

• Update README.md for significant changes
• Add JavaDoc for public APIs
• Document architectural decisions in code comments

Commit Messages (Conventional Commits):

feat: add new feature
fix: bug fix
docs: documentation changes
test: add or update tests
refactor: code refactoring
chore: maintenance tasks

Before submitting:

• All tests pass (mvn verify)
• Code coverage meets requirements (>80%)
• No compiler warnings
• Documentation updated
• Commit messages follow convention

PR Description should include:

• What: Brief description of changes
• Why: Reason for the changes
• How: Technical approach
• Testing: How you tested the changes

Mahesh Singh

Full-stack software engineer specializing in distributed systems, microservices architecture, and payment domain expertise.

• GitHub: @maheshsingh20
• LinkedIn: maheshsingh20
• Email: [email protected]

MerchantRail is engineered around mission-critical payment availability and financial integrity:

• High-Throughput Switching: Sub-50ms transaction routing via Card BIN matching and multi-issuer gRPC endpoints.
• Stand-In Processing (STIP): Autonomous offline fallback preventing transaction loss during upstream network partitions.
• Enterprise Spring Batch Clearing: Chunk-based clearing, fee netting, and ISO 20022 delivery.
• Pivotal Cloud Foundry (PCF / Tanzu): Zero-downtime rolling deployments with automated service bindings (VCAP_SERVICES).
• Full-Stack Financial Reporting: Real-time switching analytics, double-entry audit checks, and one-click reconciliation export.
• Comprehensive Quality Assurance: Unit, data-driven (Spock), integration (Testcontainers), and OWASP security scans with >85% coverage.

• Spring Team - For excellent Spring Boot framework and documentation
• Testcontainers - For revolutionizing integration testing
• OWASP - For security testing tools (ZAP, Dependency-Check)
• ISO Standards - For payment industry specifications (ISO 8583, ISO 20022)
• Apache Software Foundation - For Kafka and other open-source projects
• PostgreSQL Global Development Group - For robust database system
• Redis Labs - For high-performance caching solution
• Prometheus & Grafana - For observability infrastructure

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License

Copyright (c) 2026 Mahesh Singh

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: [email protected]

Please include:

1. Description of the issue
2. Steps to reproduce
3. Expected behavior
4. Actual behavior
5. System information (OS, Java version, Docker version)
6. Log files (if applicable)

Open a GitHub issue with the label enhancement and describe:

1. The feature you'd like to see
2. Why it would be useful
3. How it might work

Current Version: 1.0.0-SNAPSHOT
Status: ✅ Production-Ready (Core Features Complete)
Build Status: ✅ Passing
Test Coverage: ✅ 85%+ (domain/application layers)
Last Updated: July 20, 2026