# abhishek1913/upi-checkout-reconciliation architecture

> Architecture diagram of the GitHub repository abhishek1913/upi-checkout-reconciliation, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhishek1913/upi-checkout-reconciliation
- Repository: https://github.com/abhishek1913/upi-checkout-reconciliation

## Overview

This is a Spring Boot UPI checkout service. Customers create idempotent orders, start a collect or intent payment, and query order status and the payment timeline. Gateway outcomes arrive through authenticated, duplicate-prone webhooks; scheduled reconciliation checks unresolved attempts and expires overdue orders. The README also documents a deliberately unreliable simulator and a Cashfree sandbox integration. Sampled services show key orchestration, but several domain modules were not inspected, so links between those modules are limited to documented behavior.

Main entry points: [`src/main/java/com/abhishekshukla/checkout/payment/PaymentInitiationService.java`](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/PaymentInitiationService.java) (Payment initiation), [`src/main/java/com/abhishekshukla/checkout/webhook/WebhookIngestionService.java`](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/webhook/WebhookIngestionService.java) (Webhook ingestion), [`src/main/java/com/abhishekshukla/checkout/gateway/PaymentGateway.java`](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/gateway/PaymentGateway.java) (Gateway interface), [`src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationService.java`](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationService.java) (Reconciliation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_checkout["Orders and payments"]
  node_order_api["Order API"]
  node_order_service["Order service<br/>[OrderService.java]"]
  node_payment_api["Payment API"]
  node_initiation["Payment initiation"]
  node_session["Session provisioner"]
  node_attempt_ledger["Attempt ledger"]
  node_applier["Payment applier"]
  node_query["Payment queries"]
end

subgraph group_gateway["Gateway integrations"]
  node_payment_gateway["Gateway interface"]
  node_cashfree["Cashfree adapter"]
  node_simulator["Gateway simulator"]
  node_gateway_webhooks["Webhook verifier"]
end

subgraph group_reliability["Event reliability"]
  node_idempotency["Idempotency"]
  node_webhook_api["Webhook API"]
  node_ingestion["Webhook ingestion"]
  node_inbox["Webhook inbox<br/>[WebhookInbox.java]"]
  node_reconciliation["Reconciliation"]
  node_reconciler["Attempt reconciler"]
  node_discrepancy_api["Discrepancy API"]
  node_discrepancy_service["Discrepancy service"]
end

subgraph group_state["Persistence and audit"]
  node_idempotency_store["Key store"]
  node_order_repo["Order repository"]
  node_postgres[("PostgreSQL")]
  node_reconcile_queue["Reconciliation queue"]
  node_discrepancy_repo["Discrepancy repository"]
end

node_customer(("Customer"))
node_cashfree_service["Cashfree PG"]

node_customer -->|"creates order"| node_order_api
node_order_api -->|"calls"| node_order_service
node_order_service -->|"executes safely"| node_idempotency
node_idempotency -->|"claims and replays"| node_idempotency_store
node_idempotency_store -->|"reads and writes"| node_postgres
node_order_service -->|"saves and reads"| node_order_repo
node_order_repo -->|"reads and writes"| node_postgres
node_customer -->|"starts payment"| node_payment_api
node_payment_api -->|"calls"| node_initiation
node_initiation -->|"provisions session"| node_session
node_initiation -->|"opens attempt"| node_attempt_ledger
node_initiation -->|"initiates payment"| node_payment_gateway
node_cashfree -->|"implements"| node_payment_gateway
node_simulator -->|"implements"| node_payment_gateway
node_cashfree -.->|"calls"| node_cashfree_service
node_customer -->|"gateway delivers"| node_webhook_api
node_cashfree_service -.->|"sends webhook"| node_webhook_api
node_webhook_api -->|"passes delivery"| node_ingestion
node_ingestion -->|"authenticates"| node_gateway_webhooks
node_ingestion -->|"records delivery"| node_inbox
node_ingestion -->|"applies payment update"| node_applier
node_inbox -->|"records events"| node_postgres
node_applier -->|"updates attempt"| node_attempt_ledger
node_customer -->|"checks status"| node_query
node_query -->|"checks order"| node_order_repo
node_query -->|"reads attempts and timeline"| node_postgres
node_reconciliation -->|"claims due attempts"| node_reconcile_queue
node_reconciliation -->|"reconciles attempts"| node_reconciler
node_reconciliation -->|"expires overdue orders"| node_postgres
node_reconciler -->|"checks gateway"| node_payment_gateway
node_customer -->|"views discrepancies"| node_discrepancy_api
node_discrepancy_api -->|"calls"| node_discrepancy_service
node_discrepancy_service -->|"reads open records"| node_discrepancy_repo
node_discrepancy_repo -->|"reads and writes"| node_postgres

click node_order_api "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/order/OrderController.java"
click node_order_service "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/order/OrderService.java"
click node_idempotency "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/idempotency/IdempotencyService.java"
click node_idempotency_store "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/idempotency/IdempotencyStore.java"
click node_order_repo "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/order/OrderRepository.java"
click node_payment_api "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/PaymentController.java"
click node_initiation "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/PaymentInitiationService.java"
click node_session "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/GatewaySessionProvisioner.java"
click node_attempt_ledger "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/PaymentAttemptLedger.java"
click node_payment_gateway "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/gateway/PaymentGateway.java"
click node_cashfree "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/gateway/cashfree/CashfreeGateway.java"
click node_simulator "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/gateway/simulator/SimulatedGateway.java"
click node_webhook_api "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/webhook/WebhookController.java"
click node_ingestion "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/webhook/WebhookIngestionService.java"
click node_gateway_webhooks "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/gateway/cashfree/CashfreeWebhooks.java"
click node_inbox "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/webhook/WebhookInbox.java"
click node_applier "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/GatewayPaymentApplier.java"
click node_query "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/PaymentQueryService.java"
click node_reconciliation "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationService.java"
click node_reconciler "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/reconciliation/AttemptReconciler.java"
click node_reconcile_queue "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationQueue.java"
click node_discrepancy_api "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyController.java"
click node_discrepancy_service "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyService.java"
click node_discrepancy_repo "https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyRepository.java"

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_order_api,node_order_service,node_payment_api,node_initiation,node_session,node_attempt_ledger,node_applier,node_query toneBlue
class node_payment_gateway,node_cashfree,node_simulator,node_gateway_webhooks toneAmber
class node_idempotency,node_webhook_api,node_ingestion,node_inbox,node_reconciliation,node_reconciler,node_discrepancy_api,node_discrepancy_service toneMint
class node_idempotency_store,node_order_repo,node_postgres,node_reconcile_queue,node_discrepancy_repo toneRose
class node_customer,node_cashfree_service toneIndigo
```

## Components

### Orders and payments

- [Order API](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/order/OrderController.java): `src/main/java/com/abhishekshukla/checkout/order/OrderController.java`
- [Order service](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/order/OrderService.java): `src/main/java/com/abhishekshukla/checkout/order/OrderService.java`
- [Payment API](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/PaymentController.java): `src/main/java/com/abhishekshukla/checkout/payment/PaymentController.java`
- [Payment initiation](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/PaymentInitiationService.java): `src/main/java/com/abhishekshukla/checkout/payment/PaymentInitiationService.java`
- [Session provisioner](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/GatewaySessionProvisioner.java): `src/main/java/com/abhishekshukla/checkout/payment/GatewaySessionProvisioner.java`
- [Attempt ledger](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/PaymentAttemptLedger.java): `src/main/java/com/abhishekshukla/checkout/payment/PaymentAttemptLedger.java`
- [Payment applier](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/GatewayPaymentApplier.java): `src/main/java/com/abhishekshukla/checkout/payment/GatewayPaymentApplier.java`
- [Payment queries](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/payment/PaymentQueryService.java): `src/main/java/com/abhishekshukla/checkout/payment/PaymentQueryService.java`

### Gateway integrations

- [Gateway interface](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/gateway/PaymentGateway.java): `src/main/java/com/abhishekshukla/checkout/gateway/PaymentGateway.java`
- [Cashfree adapter](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/gateway/cashfree/CashfreeGateway.java): `src/main/java/com/abhishekshukla/checkout/gateway/cashfree/CashfreeGateway.java`
- [Gateway simulator](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/gateway/simulator/SimulatedGateway.java): `src/main/java/com/abhishekshukla/checkout/gateway/simulator/SimulatedGateway.java`
- [Webhook verifier](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/gateway/cashfree/CashfreeWebhooks.java): `src/main/java/com/abhishekshukla/checkout/gateway/cashfree/CashfreeWebhooks.java`

### Event reliability

- [Idempotency](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/idempotency/IdempotencyService.java): `src/main/java/com/abhishekshukla/checkout/idempotency/IdempotencyService.java`
- [Webhook API](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/webhook/WebhookController.java): `src/main/java/com/abhishekshukla/checkout/webhook/WebhookController.java`
- [Webhook ingestion](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/webhook/WebhookIngestionService.java): `src/main/java/com/abhishekshukla/checkout/webhook/WebhookIngestionService.java`
- [Webhook inbox](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/webhook/WebhookInbox.java): `src/main/java/com/abhishekshukla/checkout/webhook/WebhookInbox.java`
- [Reconciliation](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationService.java): `src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationService.java`
- [Attempt reconciler](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/reconciliation/AttemptReconciler.java): `src/main/java/com/abhishekshukla/checkout/reconciliation/AttemptReconciler.java`
- [Discrepancy API](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyController.java): `src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyController.java`
- [Discrepancy service](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyService.java): `src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyService.java`

### Persistence and audit

- [Key store](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/idempotency/IdempotencyStore.java): `src/main/java/com/abhishekshukla/checkout/idempotency/IdempotencyStore.java`
- [Order repository](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/order/OrderRepository.java): `src/main/java/com/abhishekshukla/checkout/order/OrderRepository.java`
- **PostgreSQL**
- [Reconciliation queue](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationQueue.java): `src/main/java/com/abhishekshukla/checkout/reconciliation/ReconciliationQueue.java`
- [Discrepancy repository](https://github.com/abhishek1913/upi-checkout-reconciliation/blob/main/src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyRepository.java): `src/main/java/com/abhishekshukla/checkout/discrepancy/DiscrepancyRepository.java`

### Other components

- **Customer**
- **Cashfree PG**

## Connections

- Customer → Order API: creates order
- Order API → Order service: calls
- Order service → Idempotency: executes safely
- Idempotency → Key store: claims and replays
- Key store → PostgreSQL: reads and writes
- Order service → Order repository: saves and reads
- Order repository → PostgreSQL: reads and writes
- Customer → Payment API: starts payment
- Payment API → Payment initiation: calls
- Payment initiation → Session provisioner: provisions session
- Payment initiation → Attempt ledger: opens attempt
- Payment initiation → Gateway interface: initiates payment
- Cashfree adapter → Gateway interface: implements
- Gateway simulator → Gateway interface: implements
- Cashfree adapter → Cashfree PG: calls
- Customer → Webhook API: gateway delivers
- Cashfree PG → Webhook API: sends webhook
- Webhook API → Webhook ingestion: passes delivery
- Webhook ingestion → Webhook verifier: authenticates
- Webhook ingestion → Webhook inbox: records delivery
- Webhook ingestion → Payment applier: applies payment update
- Webhook inbox → PostgreSQL: records events
- Payment applier → Attempt ledger: updates attempt
- Customer → Payment queries: checks status
- Payment queries → Order repository: checks order
- Payment queries → PostgreSQL: reads attempts and timeline
- Reconciliation → Reconciliation queue: claims due attempts
- Reconciliation → Attempt reconciler: reconciles attempts
- Reconciliation → PostgreSQL: expires overdue orders
- Attempt reconciler → Gateway interface: checks gateway
- Customer → Discrepancy API: views discrepancies
- Discrepancy API → Discrepancy service: calls
- Discrepancy service → Discrepancy repository: reads open records
- Discrepancy repository → PostgreSQL: reads and writes