# prateesh-sulikeri/distributed-payment-gateway architecture

> Architecture diagram of the GitHub repository prateesh-sulikeri/distributed-payment-gateway, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/prateesh-sulikeri/distributed-payment-gateway
- Repository: https://github.com/prateesh-sulikeri/distributed-payment-gateway

## Overview

This repo is a multi-service distributed payment gateway, not a single application. Each service is a standalone Spring Boot 4 app with its own Gradle build, database schema migrations, and runtime port. The architecture is centered on one synchronous control plane for merchant and payment APIs, and one asynchronous event pipeline over Kafka for payment processing, notifications, and settlement.

The main runtime services are:
- `merchant-service` on 8082 for merchant registration and API-key issuance.
- `payment-service` on 8080 as the core payment orchestrator.
- `mock-bank-service` on 8081 as a bank simulator / payment processor.
- `webhook-service` on 8083 for merchant-facing webhook delivery.
- `settlement-service` on 8084 for end-of-day aggregation and settlement.
An `auth-service` and `api-gateway` are planned but not implemented yet.

`merchant-service` is the source of truth for merchant identity, status, and API key generation. Its package layout is simple: controller, service, repository, entity, DTO, mapper, and a security helper for API-key generation. Other services call it via client classes rather than sharing a database, so merchant validation remains a service boundary.

`payment-service` is the central transaction coordinator. It exposes payment endpoints, validates requests with an `ApiKeyValidationFilter`, looks up merchant data through `MerchantServiceClient`, persists payments in PostgreSQL, and uses a `PaymentCacheService` plus distributed locking (`DistributedLock`, `LockService`, `LockRepository`) to guard against duplicate or concurrent processing. This service also contains the transactional outbox pieces, which is a key architectural boundary: business writes happen in the database first, and Kafka publication is handled separately and reliably by `OutboxPublisherJob`.

The payment event flow starts in `payment-service` with a `PaymentInitiatedEvent`. That event is published to Kafka, then consumed by `mock-bank-service`. The bank simulator processes the request, routes it to a payment-method-specific processor, and emits a `PaymentProcessedEvent` back to Kafka. `payment-service` has a consumer for that processed event and then emits a `PaymentSucceededEvent` for downstream consumers once the bank result is accepted.

`mock-bank-service` is the simulated external payment rail. It includes a router and multiple processors (`CardProcessor`, `UpiProcessor`, `NetBankingProcessor`) built on a shared abstract processor. This makes the bank layer pluggable by payment method and keeps the simulated authorization/processing logic isolated from the main payment domain. It has both REST and Kafka entry points, so it can behave like a mock remote bank as well as an event-driven processor.

`webhook-service` handles merchant notifications after payment processing. It consumes `PaymentProcessedEvent`, looks up merchant metadata through `MerchantServiceClient`, and persists delivery attempts in `WebhookDelivery`. A retry job (`WebhookRetryJob`) indicates that failed deliveries are retried asynchronously rather than blocking the payment path. This service is the outbound integration boundary toward merchant systems.

`settlement-service` is the end-of-day financial aggregation layer. It consumes `PaymentSucceededEvent`, groups and stores settlement data, and uses Spring Batch components (`SettlementBatchConfig`, `SettlementScheduler`, `SettlementTasklet`, `SettlementProcessor`) to run batch settlement jobs. Its repository/model split suggests it writes both settlement headers and per-payment settlement records, making it the reporting/clearing boundary of the system.

The shared infrastructure is important to the architecture: Kafka carries inter-service events, PostgreSQL stores service-owned state, Redis is used only in `payment-service` for locking/caching, and Flyway manages schema evolution per service. Docker Compose is the local environment glue for standing up those dependencies.

Cross-cutting concerns are implemented per service instead of in a shared platform layer. Examples include API-key validation in `payment-service`, global exception handling there, REST client configs in services that need merchant lookups, and Kafka producer/consumer configs in all event-driven services. This keeps each service independently deployable, but also means the diagram should show repeated infrastructure dependencies rather than a single shared runtime.

The most important architectural arrows to capture are:
1. Merchant onboarding in `merchant-service`.
2. Payment request enters `payment-service`.
3. `payment-service` validates merchant/API key and writes payment state.
4. `payment-service` publishes `PaymentInitiatedEvent` to Kafka.
5. `mock-bank-service` consumes it, processes it, and emits `PaymentProcessedEvent`.
6. `payment-service` and `webhook-service` react to the processed event.
7. `payment-service` emits `PaymentSucceededEvent`.
8. `settlement-service` consumes success events and builds batch settlements.

The planned `api-gateway` and `auth-service` are not part of the implemented topology yet, so the current architecture is still service-by-service rather than gateway-first or centralized-auth-first.

Main entry points: [`docker-compose.yml`](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/docker-compose.yml) (Docker Compose), [`payment-service/src/main/java/com/payments/payment_service/payment/service/impl/PaymentServiceImpl.java`](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/service/impl/PaymentServiceImpl.java) (Payment Core), [`settlement-service/src/main/java/com/payments/settlement_service/SettlementServiceApplication.java`](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/settlement-service/src/main/java/com/payments/settlement_service/SettlementServiceApplication.java) (Settlement App), [`merchant-service/src/main/java/com/payments/merchant_service/service/impl/MerchantServiceImpl.java`](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/merchant-service/src/main/java/com/payments/merchant_service/service/impl/MerchantServiceImpl.java) (Merchant Core)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_merchant["Merchant Service"]
  node_merchant_app(("Merchant App<br/>Spring Boot app"))
  node_merchant_api["Merchant API<br/>controller"]
  node_merchant_core["Merchant Core"]
  node_merchant_data[("Merchant Store<br/>repository/entity")]
end

subgraph group_payment["Payment Service"]
  node_payment_app(("Payment App<br/>Spring Boot app"))
  node_payment_api["Payment API<br/>controller/filter"]
  node_payment_core["Payment Core"]
  node_merchant_client["Merchant Client<br/>rest client"]
  node_payment_data[("Payment Store<br/>repository/entity")]
  node_outbox_job["Outbox Job<br/>outbox publisher"]
  node_payment_runtime{{"Locking Cache<br/>redis lock/cache<br/>[LockService.java]"}}
  node_payment_events["Payment Events<br/>event producer/consumer"]
end

subgraph group_bank["Mock Bank"]
  node_bank_app(("Bank App<br/>Spring Boot app"))
  node_bank_router["Payment Router<br/>[PaymentRouter.java]"]
  node_bank_processors["Processors"]
  node_bank_events["Bank Events<br/>Kafka consumer/producer"]
end

subgraph group_webhook["Webhook Service"]
  node_webhook_app(("Webhook App<br/>Spring Boot app"))
  node_webhook_delivery["Webhook Delivery<br/>service/entity"]
  node_webhook_retry["Retry Job<br/>scheduler"]
  node_webhook_events["Webhook Events<br/>Kafka consumer"]
end

subgraph group_settlement["Settlement Service"]
  node_settlement_app(("Settlement App<br/>Spring Boot app"))
  node_settlement_batch["Batch Pipeline<br/>batch config"]
  node_settlement_agg["Settlement Core<br/>aggregation service"]
  node_settlement_data[("Settlement Store<br/>repository/domain")]
end

subgraph group_infra["Shared Infra"]
  node_kafka{{"Kafka<br/>event bus"}}
  node_postgres[("PostgreSQL<br/>service database")]
  node_redis[("Redis<br/>cache/lock store")]
  node_compose["Docker Compose<br/>local runtime<br/>[docker-compose.yml]"]
end

node_merchant_api -->|"delegates"| node_merchant_core
node_merchant_core -->|"persists"| node_merchant_data
node_merchant_core -.->|"runs in"| node_merchant_app
node_payment_api -->|"delegates"| node_payment_core
node_payment_api -->|"validates merchant"| node_merchant_client
node_payment_core -->|"looks up"| node_merchant_client
node_payment_core -->|"persists"| node_payment_data
node_payment_core -->|"locks/cache"| node_payment_runtime
node_payment_core -->|"creates events"| node_payment_events
node_outbox_job -->|"publishes"| node_kafka
node_payment_events -->|"publishes/consumes"| node_kafka
node_bank_events -->|"consumes/publishes"| node_kafka
node_bank_events -->|"routes"| node_bank_router
node_bank_router -->|"selects"| node_bank_processors
node_webhook_events -->|"consumes"| node_kafka
node_webhook_events -->|"creates deliveries"| node_webhook_delivery
node_webhook_delivery -->|"retries via"| node_webhook_retry
node_webhook_delivery -->|"enriches merchant"| node_merchant_client
node_settlement_batch -->|"orchestrates"| node_settlement_agg
node_settlement_agg -->|"persists"| node_settlement_data
node_settlement_app -->|"consumes"| node_kafka
node_settlement_app -.->|"runs"| node_settlement_batch
node_merchant_app -->|"uses"| node_postgres
node_payment_app -->|"uses"| node_postgres
node_payment_app -->|"uses"| node_redis
node_bank_app -->|"uses"| node_kafka
node_webhook_app -->|"uses"| node_kafka
node_settlement_app -->|"uses"| node_postgres
node_compose -.->|"starts"| node_merchant_app
node_compose -.->|"starts"| node_payment_app
node_compose -.->|"starts"| node_bank_app
node_compose -.->|"starts"| node_webhook_app
node_compose -.->|"starts"| node_settlement_app
node_compose -.->|"provides"| node_kafka
node_compose -.->|"provides"| node_postgres
node_compose -.->|"provides"| node_redis

click node_merchant_app "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/merchant-service/src/main/java/com/payments/merchant_service/MerchantServiceApplication.java"
click node_merchant_api "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/merchant-service/src/main/java/com/payments/merchant_service/controller/MerchantController.java"
click node_merchant_core "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/merchant-service/src/main/java/com/payments/merchant_service/service/impl/MerchantServiceImpl.java"
click node_merchant_data "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/merchant-service/src/main/java/com/payments/merchant_service/repository/MerchantRepository.java"
click node_payment_app "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/PaymentServiceApplication.java"
click node_payment_api "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/controller/PaymentController.java"
click node_payment_core "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/service/impl/PaymentServiceImpl.java"
click node_merchant_client "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/client/MerchantServiceClient.java"
click node_payment_data "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/repository/PaymentRepository.java"
click node_outbox_job "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/event/outbox/OutboxPublisherJob.java"
click node_payment_runtime "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/common/lock/LockService.java"
click node_payment_events "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/event/PaymentEventProducer.java"
click node_bank_app "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/mock-bank-service/src/main/java/com/payments/mock_bank_service/MockBankServiceApplication.java"
click node_bank_router "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/mock-bank-service/src/main/java/com/payments/mock_bank_service/processor/PaymentRouter.java"
click node_bank_processors "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/mock-bank-service/src/main/java/com/payments/mock_bank_service/processor/AbstractPaymentProcessor.java"
click node_bank_events "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/mock-bank-service/src/main/java/com/payments/mock_bank_service/event/PaymentInitiatedConsumer.java"
click node_webhook_app "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/webhook-service/src/main/java/com/payments/webhook_service/WebhookServiceApplication.java"
click node_webhook_delivery "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/webhook-service/src/main/java/com/payments/webhook_service/service/impl/WebhookDeliveryServiceImpl.java"
click node_webhook_retry "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/webhook-service/src/main/java/com/payments/webhook_service/job/WebhookRetryJob.java"
click node_webhook_events "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/webhook-service/src/main/java/com/payments/webhook_service/event/PaymentProcessedConsumer.java"
click node_settlement_app "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/settlement-service/src/main/java/com/payments/settlement_service/SettlementServiceApplication.java"
click node_settlement_batch "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/settlement-service/src/main/java/com/payments/settlement_service/config/SettlementBatchConfig.java"
click node_settlement_agg "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/settlement-service/src/main/java/com/payments/settlement_service/service/impl/SettlementAggregationServiceImpl.java"
click node_settlement_data "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/settlement-service/src/main/java/com/payments/settlement_service/repository/SettlementRepository.java"
click node_compose "https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/docker-compose.yml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_merchant_app,node_merchant_api,node_merchant_core,node_merchant_data toneBlue
class node_payment_app,node_payment_api,node_payment_core,node_merchant_client,node_payment_data,node_outbox_job,node_payment_runtime,node_payment_events toneAmber
class node_bank_app,node_bank_router,node_bank_processors,node_bank_events toneMint
class node_webhook_app,node_webhook_delivery,node_webhook_retry,node_webhook_events toneRose
class node_settlement_app,node_settlement_batch,node_settlement_agg,node_settlement_data toneIndigo
class node_kafka,node_postgres,node_redis,node_compose toneTeal
```

## Components

### Merchant Service

Merchant onboarding and API-key issuance

- [Merchant App](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/merchant-service/src/main/java/com/payments/merchant_service/MerchantServiceApplication.java): Spring Boot app · Merchant registration and API-key issuance runtime · `merchant-service/src/main/java/com/payments/merchant_service/MerchantServiceApplication.java`
- [Merchant API](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/merchant-service/src/main/java/com/payments/merchant_service/controller/MerchantController.java): controller · Merchant registration and lookup endpoints · `merchant-service/src/main/java/com/payments/merchant_service/controller/MerchantController.java`
- [Merchant Core](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/merchant-service/src/main/java/com/payments/merchant_service/service/impl/MerchantServiceImpl.java): service · Owns merchant identity, status, and API-key generation · `merchant-service/src/main/java/com/payments/merchant_service/service/impl/MerchantServiceImpl.java`
- [Merchant Store](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/merchant-service/src/main/java/com/payments/merchant_service/repository/MerchantRepository.java): repository/entity · Merchant persistence and domain model · `merchant-service/src/main/java/com/payments/merchant_service/repository/MerchantRepository.java`

### Payment Service

Core payment orchestration and transactional outbox

- [Payment App](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/PaymentServiceApplication.java): Spring Boot app · Central payment orchestration runtime · `payment-service/src/main/java/com/payments/payment_service/PaymentServiceApplication.java`
- [Payment API](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/controller/PaymentController.java): controller/filter · Payment endpoints and API-key validation boundary · `payment-service/src/main/java/com/payments/payment_service/payment/controller/PaymentController.java`
- [Payment Core](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/service/impl/PaymentServiceImpl.java): service · Validates, coordinates, and persists payments · `payment-service/src/main/java/com/payments/payment_service/payment/service/impl/PaymentServiceImpl.java`
- [Merchant Client](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/client/MerchantServiceClient.java): rest client · Merchant lookup client used for validation and enrichment · `payment-service/src/main/java/com/payments/payment_service/payment/client/MerchantServiceClient.java`
- [Payment Store](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/repository/PaymentRepository.java): repository/entity · Payment persistence and domain state · `payment-service/src/main/java/com/payments/payment_service/payment/repository/PaymentRepository.java`
- [Outbox Job](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/event/outbox/OutboxPublisherJob.java): outbox publisher · Publishes database-backed events to Kafka reliably · `payment-service/src/main/java/com/payments/payment_service/payment/event/outbox/OutboxPublisherJob.java`
- [Locking Cache](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/common/lock/LockService.java): redis lock/cache · Duplicate protection and concurrent processing guard · `payment-service/src/main/java/com/payments/payment_service/common/lock/LockService.java`
- [Payment Events](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/payment-service/src/main/java/com/payments/payment_service/payment/event/PaymentEventProducer.java): event producer/consumer · Initiated, processed, and succeeded payment events · `payment-service/src/main/java/com/payments/payment_service/payment/event/PaymentEventProducer.java`

### Mock Bank

Simulated external payment rail and processor

- [Bank App](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/mock-bank-service/src/main/java/com/payments/mock_bank_service/MockBankServiceApplication.java): Spring Boot app · Mock bank simulator runtime · `mock-bank-service/src/main/java/com/payments/mock_bank_service/MockBankServiceApplication.java`
- [Payment Router](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/mock-bank-service/src/main/java/com/payments/mock_bank_service/processor/PaymentRouter.java): router · Dispatches by payment method to processors · `mock-bank-service/src/main/java/com/payments/mock_bank_service/processor/PaymentRouter.java`
- [Processors](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/mock-bank-service/src/main/java/com/payments/mock_bank_service/processor/AbstractPaymentProcessor.java): payment processors · Card, UPI, and netbanking processing implementations · `mock-bank-service/src/main/java/com/payments/mock_bank_service/processor/AbstractPaymentProcessor.java`
- [Bank Events](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/mock-bank-service/src/main/java/com/payments/mock_bank_service/event/PaymentInitiatedConsumer.java): Kafka consumer/producer · Consumes initiated events and emits processed events · `mock-bank-service/src/main/java/com/payments/mock_bank_service/event/PaymentInitiatedConsumer.java`

### Webhook Service

Merchant notification delivery and retries

- [Webhook App](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/webhook-service/src/main/java/com/payments/webhook_service/WebhookServiceApplication.java): Spring Boot app · Merchant notification delivery runtime · `webhook-service/src/main/java/com/payments/webhook_service/WebhookServiceApplication.java`
- [Webhook Delivery](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/webhook-service/src/main/java/com/payments/webhook_service/service/impl/WebhookDeliveryServiceImpl.java): service/entity · Persists delivery attempts and status · `webhook-service/src/main/java/com/payments/webhook_service/service/impl/WebhookDeliveryServiceImpl.java`
- [Retry Job](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/webhook-service/src/main/java/com/payments/webhook_service/job/WebhookRetryJob.java): scheduler · Asynchronous retry path for failed webhook deliveries · `webhook-service/src/main/java/com/payments/webhook_service/job/WebhookRetryJob.java`
- [Webhook Events](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/webhook-service/src/main/java/com/payments/webhook_service/event/PaymentProcessedConsumer.java): Kafka consumer · Consumes payment processed events for merchant notifications · `webhook-service/src/main/java/com/payments/webhook_service/event/PaymentProcessedConsumer.java`

### Settlement Service

End-of-day aggregation and batch settlement

- [Settlement App](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/settlement-service/src/main/java/com/payments/settlement_service/SettlementServiceApplication.java): Spring Boot app · Batch settlement and aggregation runtime · `settlement-service/src/main/java/com/payments/settlement_service/SettlementServiceApplication.java`
- [Batch Pipeline](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/settlement-service/src/main/java/com/payments/settlement_service/config/SettlementBatchConfig.java): batch config · Scheduler, tasklet, and processor for settlement runs · `settlement-service/src/main/java/com/payments/settlement_service/config/SettlementBatchConfig.java`
- [Settlement Core](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/settlement-service/src/main/java/com/payments/settlement_service/service/impl/SettlementAggregationServiceImpl.java): aggregation service · Groups successful payments into settlement records · `settlement-service/src/main/java/com/payments/settlement_service/service/impl/SettlementAggregationServiceImpl.java`
- [Settlement Store](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/settlement-service/src/main/java/com/payments/settlement_service/repository/SettlementRepository.java): repository/domain · Settlement headers and per-payment records · `settlement-service/src/main/java/com/payments/settlement_service/repository/SettlementRepository.java`

### Shared Infra

Cross-service messaging, storage, and local environment

- **Kafka**: event bus · Inter-service event transport
- **PostgreSQL**: service database · Service-owned persistent state
- **Redis**: cache/lock store · Distributed locks and payment cache
- [Docker Compose](https://github.com/prateesh-sulikeri/distributed-payment-gateway/blob/main/docker-compose.yml): local runtime · Local environment orchestration for dependencies and services · `docker-compose.yml`

## Connections

- Merchant API → Merchant Core: delegates · Controller routes onboarding and lookup requests to domain logic
- Merchant Core → Merchant Store: persists · Merchant records are stored in the service-owned database
- Merchant Core → Merchant App: runs in · Core merchant logic is part of the Spring Boot runtime
- Payment API → Payment Core: delegates · Payment endpoints hand off to orchestration logic
- Payment API → Merchant Client: validates merchant · API-key and merchant checks use the merchant service boundary
- Payment Core → Merchant Client: looks up · Payment processing enriches and validates merchant data remotely
- Payment Core → Payment Store: persists · Payment state is written to PostgreSQL first
- Payment Core → Locking Cache: locks/cache · Duplicate prevention and fast reads use Redis-backed helpers
- Payment Core → Payment Events: creates events · Payment orchestration emits initiated and success events
- Outbox Job → Kafka: publishes · Outbox entries are published asynchronously to Kafka
- Payment Events → Kafka: publishes/consumes · Payment-service produces initiated and succeeded events and consumes processed events
- Bank Events → Kafka: consumes/publishes · Mock bank consumes initiated events and emits processed results
- Bank Events → Payment Router: routes · Incoming payment requests are dispatched by method
- Payment Router → Processors: selects · Card, UPI, and netbanking processors implement method-specific behavior
- Webhook Events → Kafka: consumes · Webhook delivery starts from processed payment events
- Webhook Events → Webhook Delivery: creates deliveries · Processed payments are turned into delivery attempts
- Webhook Delivery → Retry Job: retries via · Failed deliveries are retried asynchronously
- Webhook Delivery → Merchant Client: enriches merchant · Merchant metadata is fetched before notification delivery
- Batch Pipeline → Settlement Core: orchestrates · Batch configuration drives settlement aggregation steps
- Settlement Core → Settlement Store: persists · Settlement headers and payment records are stored locally
- Settlement App → Kafka: consumes · Settlement is triggered by success events from the payment flow
- Settlement App → Batch Pipeline: runs · Batch runtime hosts scheduled settlement jobs
- Merchant App → PostgreSQL: uses · Merchant service owns its PostgreSQL schema
- Payment App → PostgreSQL: uses · Payment service persists business and outbox state
- Payment App → Redis: uses · Payment service is the only Redis consumer
- Bank App → Kafka: uses · Bank service participates in the event pipeline
- Webhook App → Kafka: uses · Webhook service reacts to payment events
- Settlement App → PostgreSQL: uses · Settlement service stores settlement aggregates in its own database
- Docker Compose → Merchant App: starts · Local compose brings up each standalone service
- Docker Compose → Payment App: starts · Local compose brings up each standalone service
- Docker Compose → Bank App: starts · Local compose brings up each standalone service
- Docker Compose → Webhook App: starts · Local compose brings up each standalone service
- Docker Compose → Settlement App: starts · Local compose brings up each standalone service
- Docker Compose → Kafka: provides · Compose coordinates shared event infrastructure
- Docker Compose → PostgreSQL: provides · Compose coordinates shared database infrastructure
- Docker Compose → Redis: provides · Compose coordinates shared cache infrastructure
