# abhishekdwivedi29/payprox architecture

> Architecture diagram of the GitHub repository abhishekdwivedi29/payprox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/abhishekdwivedi29/payprox
- Repository: https://github.com/abhishekdwivedi29/payprox

## Overview

1. **System shape**
   - PayProX is a microservice-based payment ecosystem built with **Node.js + Express** services, **MongoDB** per service, and **React/Vite** frontends.
   - The core architectural boundary is that each service owns a narrow business domain and exposes REST APIs; cross-service calls happen over HTTP with explicit internal authentication.

2. **Client layer**
   - There are two React frontends:
     - `frontend`: the main customer/merchant-facing product UI with payment, dashboard, refunds, settlements, and auth flows.
     - `merchant-frontend`: a smaller merchant portal focused on merchant pages and orders.
   - Both are Vite apps and appear intended for **Vercel** deployment, while backend services are deployed independently.

3. **Merchant domain service**
   - `merchant-service` owns merchant authentication and merchant lifecycle actions.
   - It exposes auth routes, merchant routes, and public routes for order creation / merchant-facing operations.
   - This service is the merchant entry point for initiating orders and triggering settlement-related actions.

4. **Customer domain service**
   - `customer-service` owns customer registration, login, and customer profile/data management.
   - It also exposes `internalRoutes` for service-to-service validation.
   - Customer-facing endpoints are protected by JWT middleware, while internal endpoints use a separate internal auth guard.

5. **Payment gateway orchestration service**
   - `payment-gateway-service` is the central workflow orchestrator for transactions, sessions, and refunds.
   - It contains:
     - payment routes and controllers for initiating payments,
     - session routes for temporary payment sessions,
     - refund routes for request/approval/execution,
     - internal routes for service coordination.
   - This service is the main transaction hub that coordinates tokenization, risk checks, issuer/acquirer actions, and persistence of `Transaction` and `Refund` records.

6. **Security and token handling**
   - Sensitive customer payment flow is protected by `verifyCustomerToken` in the payment gateway and token-related middleware in the tokenization service.
   - `tokenization-service` replaces raw card data with non-reversible tokens and stores only token metadata in `CardToken`.
   - A shared helper exists at `backend/shared/auth/setAuthCookie.js`, indicating cookie-based auth setup in addition to JWT handling.

7. **Fraud/risk boundary**
   - `risk-engine` is a stateless fraud-prevention layer invoked during payment processing.
   - It evaluates transaction metadata using rule-based checks such as velocity, thresholds, and blacklist logic.
   - Architecturally, it sits between payment initiation and bank authorization, acting as a gate before funds movement proceeds.

8. **Banking side: issuer and acquirer**
   - `issuer-service` handles customer-side bank account logic and debit/credit operations.
   - `acquirer-service` handles merchant-side bank account logic, merchant crediting/debiting, and balance checks.
   - Both services use internal auth middleware, which is important because they are not intended for direct public access; they are invoked by gateway/settlement workflows.

9. **Settlement processing**
   - `settlement-engine` is responsible for settlement lifecycle management and batch payout logic.
   - It has a job entry point (`jobs/runSettlement.js`) and settlement persistence via the `Settlement` model.
   - The current behavior is merchant-triggered rather than fully scheduled, but it still represents the reconciliation layer that marks eligible transactions as settled and requests merchant credit from the acquirer side.

10. **Primary transaction flow**
   - The diagram should show the flow as:
     - merchant creates an order,
     - payment gateway creates a short-lived session,
     - customer submits payment,
     - tokenization verifies card tokens or issuer verifies netbanking credentials,
     - risk engine approves/rejects,
     - acquirer/issuer execute fund movement,
     - payment gateway stores the final transaction state.
   - This makes the payment gateway the orchestration spine, with the other services acting as specialized executors.

11. **Refund flow**
   - Refunds are multi-step and cross-service:
     - customer initiates refund through the gateway,
     - refund is recorded as pending,
     - merchant approves/rejects via merchant-facing workflow,
     - gateway executes the refund using issuer credit, and if the original transaction was already settled, also triggers acquirer debit from the merchant side.
   - This flow crosses payment, merchant, issuer, and acquirer boundaries, with internal auth protecting the service calls.

12. **Data ownership and persistence**
   - Each service has its own `src/utils/db.js` and local models, indicating **database-per-service** separation rather than a shared monolith database layer.
   - Main persisted entities visible in the tree include:
     - `Transaction`, `Refund` in payment gateway,
     - `CardToken` in tokenization,
     - `Settlement` in settlement engine,
     - `Customer`, `Merchant`, and bank-account models in the domain/bank services.
   - This separation is key for architecture diagrams: the data model is distributed, not centralized.

13. **Service-to-service trust boundary**
   - Public endpoints are guarded by JWT-based middleware for end-user access.
   - Internal endpoints are guarded by `internalAuth` middleware in most backend services, forming a distinct trust boundary for backend orchestration traffic.
   - The architecture therefore has two access layers: external client auth and internal service auth.

14. **Deployment and runtime**
   - Backend services are independently deployable and container-friendly; several services include `Dockerfile`s and the backend repo includes `docker-compose.yml`.
   - The README indicates deployment on **Render** for backend services and **Vercel** for frontends.
   - This means the diagram should treat each microservice as separately hosted rather than as a single backend application.

15. **What to emphasize in a diagram**
   - Put **payment-gateway-service** at the center.
   - Connect it to **tokenization**, **risk-engine**, **issuer-service**, **acquirer-service**, **customer-service**, **merchant-service**, and **settlement-engine**.
   - Show the frontends as consumers of merchant/customer/payment APIs.
   - Show separate databases per service, plus internal-auth-protected service-to-service links.

Main entry points: [`backend/services/payment-gateway-service/src`](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/payment-gateway-service/src) (Gateway API), [`backend/services/merchant-service`](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/merchant-service) (Merchant Service), [`frontend`](https://github.com/abhishekdwivedi29/payprox/tree/main/frontend) (Customer UI), [`backend/services/payment-gateway-service`](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/payment-gateway-service) (Payment Gateway)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_clients["Clients"]
  node_frontend["Customer UI<br/>React/Vite app"]
  node_merchant_frontend["Merchant Portal<br/>React/Vite app"]
end

subgraph group_backend["Backend"]
  node_payment_gateway["Payment Gateway<br/>orchestrator"]
  node_gateway_api["Gateway API<br/>routes/controllers"]
  node_gateway_store[("Gateway DB<br/>Transaction/Refund data<br/>[db.js]")]
  node_merchant_service["Merchant Service<br/>merchant domain"]
  node_merchant_db[("Merchant DB<br/>Merchant data<br/>[db.js]")]
  node_customer_service["Customer Service<br/>customer domain"]
  node_customer_db[("Customer DB<br/>Customer data<br/>[db.js]")]
  node_tokenization_service["Tokenization<br/>card token service"]
  node_token_db[("Token DB<br/>CardToken data<br/>[db.js]")]
  node_risk_engine["Risk Engine<br/>fraud checks"]
  node_issuer_service["Issuer Service<br/>banking"]
  node_issuer_db[("Issuer DB<br/>CustomerBankAccount data<br/>[db.js]")]
  node_acquirer_service["Acquirer Service<br/>banking"]
  node_acquirer_db[("Acquirer DB<br/>MerchantBankAccount data<br/>[db.js]")]
  node_settlement_engine["Settlement Engine<br/>settlement workflow"]
  node_settlement_db[("Settlement DB<br/>Settlement data<br/>[db.js]")]
end

subgraph group_shared["Shared"]
  node_auth_cookie["Auth Cookie<br/>shared helper<br/>[setAuthCookie.js]"]
end

node_frontend -->|"customer APIs"| node_payment_gateway
node_frontend -->|"auth/profile"| node_customer_service
node_frontend -->|"merchant auth"| node_merchant_service
node_merchant_frontend -->|"orders/auth"| node_merchant_service
node_merchant_frontend -->|"order payment"| node_payment_gateway
node_payment_gateway -->|"exposes"| node_gateway_api
node_gateway_api -->|"tokenize"| node_tokenization_service
node_gateway_api -->|"risk check"| node_risk_engine
node_gateway_api -->|"debit/credit"| node_issuer_service
node_gateway_api -->|"merchant funds"| node_acquirer_service
node_gateway_api -->|"merchant flow"| node_merchant_service
node_gateway_api -->|"customer flow"| node_customer_service
node_gateway_api -->|"settlement"| node_settlement_engine
node_merchant_service -->|"persists"| node_merchant_db
node_customer_service -->|"persists"| node_customer_db
node_tokenization_service -->|"persists"| node_token_db
node_issuer_service -->|"persists"| node_issuer_db
node_acquirer_service -->|"persists"| node_acquirer_db
node_settlement_engine -->|"persists"| node_settlement_db
node_payment_gateway -->|"persists"| node_gateway_store
node_frontend -.->|"auth setup"| node_auth_cookie
node_merchant_service -.->|"auth setup"| node_auth_cookie
node_customer_service -.->|"auth setup"| node_auth_cookie

click node_frontend "https://github.com/abhishekdwivedi29/payprox/tree/main/frontend"
click node_merchant_frontend "https://github.com/abhishekdwivedi29/payprox/tree/main/merchant-frontend"
click node_payment_gateway "https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/payment-gateway-service"
click node_gateway_api "https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/payment-gateway-service/src"
click node_gateway_store "https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/payment-gateway-service/src/utils/db.js"
click node_merchant_service "https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/merchant-service"
click node_merchant_db "https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/merchant-service/src/utils/db.js"
click node_customer_service "https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/customer-service"
click node_customer_db "https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/customer-service/src/utils/db.js"
click node_tokenization_service "https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/tokenization-service"
click node_token_db "https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/tokenization-service/src/utils/db.js"
click node_risk_engine "https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/risk-engine"
click node_issuer_service "https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/issuer-service"
click node_issuer_db "https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/issuer-service/src/utils/db.js"
click node_acquirer_service "https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/acquirer-service"
click node_acquirer_db "https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/acquirer-service/src/utils/db.js"
click node_settlement_engine "https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/settlement-engine"
click node_settlement_db "https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/settlement-engine/src/utils/db.js"
click node_auth_cookie "https://github.com/abhishekdwivedi29/payprox/blob/main/backend/shared/auth/setAuthCookie.js"

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_frontend,node_merchant_frontend toneBlue
class node_payment_gateway,node_gateway_api,node_gateway_store,node_merchant_service,node_merchant_db,node_customer_service,node_customer_db,node_tokenization_service,node_token_db,node_risk_engine,node_issuer_service,node_issuer_db,node_acquirer_service,node_acquirer_db,node_settlement_engine,node_settlement_db toneAmber
class node_auth_cookie toneMint
```

## Components

### Clients

React/Vite frontends used by customers and merchants.

- [Customer UI](https://github.com/abhishekdwivedi29/payprox/tree/main/frontend): React/Vite app · Main customer and merchant-facing product frontend for payments, refunds, settlements, and dashboards. · `frontend`
- [Merchant Portal](https://github.com/abhishekdwivedi29/payprox/tree/main/merchant-frontend): React/Vite app · Merchant-focused portal for merchant pages and order flows. · `merchant-frontend`

### Backend

Independently deployable Node.js microservices and their data stores.

- [Payment Gateway](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/payment-gateway-service): orchestrator · Central transaction hub for sessions, payments, refunds, and internal coordination. · `backend/services/payment-gateway-service`
- [Gateway API](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/payment-gateway-service/src): routes/controllers · Public payment, session, and refund endpoints plus internal coordination handlers. · `backend/services/payment-gateway-service/src`
- [Gateway DB](https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/payment-gateway-service/src/utils/db.js): Transaction/Refund data · Persistent transaction and refund records owned by the payment gateway. · `backend/services/payment-gateway-service/src/utils/db.js`
- [Merchant Service](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/merchant-service): merchant domain · Merchant authentication, merchant lifecycle, and public order initiation entry point. · `backend/services/merchant-service`
- [Merchant DB](https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/merchant-service/src/utils/db.js): Merchant data · Merchant identity and lifecycle persistence. · `backend/services/merchant-service/src/utils/db.js`
- [Customer Service](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/customer-service): customer domain · Customer registration, login, profile management, and internal validation. · `backend/services/customer-service`
- [Customer DB](https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/customer-service/src/utils/db.js): Customer data · Customer identity and profile persistence. · `backend/services/customer-service/src/utils/db.js`
- [Tokenization](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/tokenization-service): card token service · Replaces raw card data with irreversible tokens and stores token metadata. · `backend/services/tokenization-service`
- [Token DB](https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/tokenization-service/src/utils/db.js): CardToken data · Stored token metadata for payment-card tokenization. · `backend/services/tokenization-service/src/utils/db.js`
- [Risk Engine](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/risk-engine): fraud checks · Stateless rule-based fraud and velocity checks in the payment path. · `backend/services/risk-engine`
- [Issuer Service](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/issuer-service): banking · Customer-side bank account validation and debit/credit execution. · `backend/services/issuer-service`
- [Issuer DB](https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/issuer-service/src/utils/db.js): CustomerBankAccount data · Bank-account persistence for issuer-side operations. · `backend/services/issuer-service/src/utils/db.js`
- [Acquirer Service](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/acquirer-service): banking · Merchant-side account checks plus merchant crediting and debiting. · `backend/services/acquirer-service`
- [Acquirer DB](https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/acquirer-service/src/utils/db.js): MerchantBankAccount data · Bank-account persistence for acquirer-side operations. · `backend/services/acquirer-service/src/utils/db.js`
- [Settlement Engine](https://github.com/abhishekdwivedi29/payprox/tree/main/backend/services/settlement-engine): settlement workflow · Settlement lifecycle and batch payout orchestration, including merchant-triggered reconciliation. · `backend/services/settlement-engine`
- [Settlement DB](https://github.com/abhishekdwivedi29/payprox/blob/main/backend/services/settlement-engine/src/utils/db.js): Settlement data · Settlement persistence for reconciliation and payout processing. · `backend/services/settlement-engine/src/utils/db.js`

### Shared

Cross-cutting helpers used across the backend.

- [Auth Cookie](https://github.com/abhishekdwivedi29/payprox/blob/main/backend/shared/auth/setAuthCookie.js): shared helper · Shared helper for cookie-based auth setup across backend flows. · `backend/shared/auth/setAuthCookie.js`

## Connections

- Customer UI → Payment Gateway: customer APIs · Customer UI calls payment, refund, transaction, and settlement APIs.
- Customer UI → Customer Service: auth/profile · Customer UI uses customer auth and profile endpoints.
- Customer UI → Merchant Service: merchant auth · Merchant-facing portions of the product use merchant auth endpoints.
- Merchant Portal → Merchant Service: orders/auth · Merchant portal calls merchant and public order endpoints.
- Merchant Portal → Payment Gateway: order payment · Merchant portal participates in payment and order initiation flows.
- Payment Gateway → Gateway API: exposes · Gateway exposes payment, session, refund, and internal routes.
- Gateway API → Tokenization: tokenize · Gateway delegates card token validation and token-related payment steps.
- Gateway API → Risk Engine: risk check · Gateway invokes fraud/risk evaluation before fund movement.
- Gateway API → Issuer Service: debit/credit · Gateway coordinates issuer-side account movement and refund crediting.
- Gateway API → Acquirer Service: merchant funds · Gateway coordinates merchant-side debits, credits, and balance checks.
- Gateway API → Merchant Service: merchant flow · Gateway coordinates merchant order and refund approval workflows.
- Gateway API → Customer Service: customer flow · Gateway validates customer identity and customer-owned payment actions.
- Gateway API → Settlement Engine: settlement · Gateway triggers settlement-related updates and post-payment reconciliation.
- Merchant Service → Merchant DB: persists · Merchant service owns merchant records and lifecycle state.
- Customer Service → Customer DB: persists · Customer service owns customer records and profiles.
- Tokenization → Token DB: persists · Tokenization service stores card-token metadata only.
- Issuer Service → Issuer DB: persists · Issuer service owns customer bank-account data.
- Acquirer Service → Acquirer DB: persists · Acquirer service owns merchant bank-account data.
- Settlement Engine → Settlement DB: persists · Settlement engine stores reconciliation and settlement state.
- Payment Gateway → Gateway DB: persists · Gateway stores final transaction and refund outcomes.
- Customer UI → Auth Cookie: auth setup · Frontend auth flows align with shared cookie-based auth behavior.
- Merchant Service → Auth Cookie: auth setup · Merchant auth flows use the shared cookie helper pattern.
- Customer Service → Auth Cookie: auth setup · Customer auth flows use the shared cookie helper pattern.
