# gnarendra9014-user/payment-wallet-system architecture

> Architecture diagram of the GitHub repository gnarendra9014-user/payment-wallet-system, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gnarendra9014-user/payment-wallet-system
- Repository: https://github.com/gnarendra9014-user/payment-wallet-system

## Overview

This is a distributed payment and digital-wallet backend. Clients create wallets and initiate transfers, top-ups, or withdrawals through REST APIs; payment requests are persisted and published as events, then the saga coordinator directs wallet mutations and reports completion or failure. Wallet operations maintain balances and transaction history, with compensation events for failures. The graph reflects the README’s documented event flow and capabilities; some consumer, model, and database wiring is based on documented responsibilities because their implementation was not sampled.

Main entry points: [`shared/kafka/kafkaClient.js`](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/shared/kafka/kafkaClient.js) (Kafka event bus), [`services/wallet-service/src/index.js`](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/index.js) (Wallet service), [`services/wallet-service/src/routes/walletRoutes.js`](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/routes/walletRoutes.js) (Wallet routes), [`services/wallet-service/src/consumers/walletConsumer.js`](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/consumers/walletConsumer.js) (Wallet consumer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["REST services"]
  node_wallet_entry["Wallet service<br/>[index.js]"]
  node_wallet_routes["Wallet routes<br/>[walletRoutes.js]"]
  node_wallet_controller["Wallet operations"]
  node_wallet_consumer["Wallet consumer<br/>[walletConsumer.js]"]
  node_payment_entry["Payment service<br/>[index.js]"]
  node_payment_routes["Payment routes<br/>[paymentRoutes.js]"]
  node_payment_controller["Payment operations"]
  node_payment_consumer["Payment consumer<br/>[paymentConsumer.js]"]
end

subgraph group_saga["Saga coordination"]
  node_saga_entry["Saga service<br/>[index.js]"]
  node_saga_consumer["Saga consumer<br/>[sagaConsumer.js]"]
  node_orchestrator["Saga state machine"]
end

subgraph group_events["Event messaging"]
  node_kafka["Kafka event bus<br/>[kafkaClient.js]"]
end

subgraph group_state["State and storage"]
  node_wallet_model["Wallet ledger<br/>[walletModel.js]"]
  node_payment_model["Payment records<br/>[paymentModel.js]"]
  node_saga_model["Saga state<br/>[sagaModel.js]"]
  node_idempotency["Idempotency middleware<br/>[idempotency.js]"]
  node_postgres[("PostgreSQL")]
  node_redis[("Redis cache")]
end

node_client(("API client"))

node_client -->|"REST requests"| node_wallet_entry
node_client -->|"REST requests"| node_payment_entry
node_wallet_entry -->|"mounts routes"| node_wallet_routes
node_wallet_routes -->|"dispatches"| node_wallet_controller
node_wallet_routes -->|"guards mutations"| node_idempotency
node_wallet_controller -->|"reads and mutates"| node_wallet_model
node_wallet_entry -->|"starts consumer"| node_wallet_consumer
node_wallet_consumer -->|"applies wallet events"| node_wallet_model
node_wallet_consumer -->|"consumes and publishes"| node_kafka
node_payment_entry -->|"mounts routes"| node_payment_routes
node_payment_routes -->|"dispatches"| node_payment_controller
node_payment_routes -->|"guards mutations"| node_idempotency
node_payment_controller -->|"creates and queries"| node_payment_model
node_payment_controller -->|"publishes initiated"| node_kafka
node_payment_entry -->|"starts consumer"| node_payment_consumer
node_payment_consumer -->|"updates payment status"| node_payment_model
node_payment_consumer -->|"consumes status events"| node_kafka
node_saga_entry -->|"starts consumer"| node_saga_consumer
node_saga_entry -->|"serves saga queries"| node_saga_model
node_saga_consumer -->|"dispatches events"| node_orchestrator
node_saga_consumer -->|"consumes events"| node_kafka
node_orchestrator -->|"creates and updates"| node_saga_model
node_orchestrator -->|"publishes saga commands"| node_kafka
node_idempotency -->|"checks cache"| node_redis
node_wallet_model -->|"persists balances and ledger"| node_postgres
node_payment_model -->|"persists payments"| node_postgres
node_saga_model -->|"persists saga state"| node_postgres

click node_wallet_entry "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/index.js"
click node_wallet_routes "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/routes/walletRoutes.js"
click node_wallet_controller "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/controllers/walletController.js"
click node_wallet_consumer "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/consumers/walletConsumer.js"
click node_wallet_model "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/models/walletModel.js"
click node_payment_entry "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/index.js"
click node_payment_routes "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/routes/paymentRoutes.js"
click node_payment_controller "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/controllers/paymentController.js"
click node_payment_consumer "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/consumers/paymentConsumer.js"
click node_payment_model "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/models/paymentModel.js"
click node_saga_entry "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/saga-orchestrator/src/index.js"
click node_saga_consumer "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/saga-orchestrator/src/consumers/sagaConsumer.js"
click node_orchestrator "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/saga-orchestrator/src/orchestrator/sagaOrchestrator.js"
click node_saga_model "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/saga-orchestrator/src/models/sagaModel.js"
click node_idempotency "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/shared/middleware/idempotency.js"
click node_kafka "https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/shared/kafka/kafkaClient.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_wallet_entry,node_wallet_routes,node_wallet_controller,node_wallet_consumer,node_payment_entry,node_payment_routes,node_payment_controller,node_payment_consumer,node_client toneBlue
class node_saga_entry,node_saga_consumer,node_orchestrator toneAmber
class node_kafka toneMint
class node_wallet_model,node_payment_model,node_saga_model,node_idempotency,node_postgres,node_redis toneRose
```

## Components

### REST services

- [Wallet service](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/index.js): `services/wallet-service/src/index.js`
- [Wallet routes](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/routes/walletRoutes.js): `services/wallet-service/src/routes/walletRoutes.js`
- [Wallet operations](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/controllers/walletController.js): `services/wallet-service/src/controllers/walletController.js`
- [Wallet consumer](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/consumers/walletConsumer.js): `services/wallet-service/src/consumers/walletConsumer.js`
- [Payment service](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/index.js): `services/payment-service/src/index.js`
- [Payment routes](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/routes/paymentRoutes.js): `services/payment-service/src/routes/paymentRoutes.js`
- [Payment operations](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/controllers/paymentController.js): `services/payment-service/src/controllers/paymentController.js`
- [Payment consumer](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/consumers/paymentConsumer.js): `services/payment-service/src/consumers/paymentConsumer.js`

### Saga coordination

- [Saga service](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/saga-orchestrator/src/index.js): `services/saga-orchestrator/src/index.js`
- [Saga consumer](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/saga-orchestrator/src/consumers/sagaConsumer.js): `services/saga-orchestrator/src/consumers/sagaConsumer.js`
- [Saga state machine](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/saga-orchestrator/src/orchestrator/sagaOrchestrator.js): `services/saga-orchestrator/src/orchestrator/sagaOrchestrator.js`

### Event messaging

- [Kafka event bus](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/shared/kafka/kafkaClient.js): `shared/kafka/kafkaClient.js`

### State and storage

- [Wallet ledger](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/wallet-service/src/models/walletModel.js): `services/wallet-service/src/models/walletModel.js`
- [Payment records](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/payment-service/src/models/paymentModel.js): `services/payment-service/src/models/paymentModel.js`
- [Saga state](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/services/saga-orchestrator/src/models/sagaModel.js): `services/saga-orchestrator/src/models/sagaModel.js`
- [Idempotency middleware](https://github.com/gnarendra9014-user/payment-wallet-system/blob/main/shared/middleware/idempotency.js): `shared/middleware/idempotency.js`
- **PostgreSQL**
- **Redis cache**

### Other components

- **API client**

## Connections

- API client → Wallet service: REST requests
- API client → Payment service: REST requests
- Wallet service → Wallet routes: mounts routes
- Wallet routes → Wallet operations: dispatches
- Wallet routes → Idempotency middleware: guards mutations
- Wallet operations → Wallet ledger: reads and mutates
- Wallet service → Wallet consumer: starts consumer
- Wallet consumer → Wallet ledger: applies wallet events
- Wallet consumer → Kafka event bus: consumes and publishes
- Payment service → Payment routes: mounts routes
- Payment routes → Payment operations: dispatches
- Payment routes → Idempotency middleware: guards mutations
- Payment operations → Payment records: creates and queries
- Payment operations → Kafka event bus: publishes initiated
- Payment service → Payment consumer: starts consumer
- Payment consumer → Payment records: updates payment status
- Payment consumer → Kafka event bus: consumes status events
- Saga service → Saga consumer: starts consumer
- Saga service → Saga state: serves saga queries
- Saga consumer → Saga state machine: dispatches events
- Saga consumer → Kafka event bus: consumes events
- Saga state machine → Saga state: creates and updates
- Saga state machine → Kafka event bus: publishes saga commands
- Idempotency middleware → Redis cache: checks cache
- Wallet ledger → PostgreSQL: persists balances and ledger
- Payment records → PostgreSQL: persists payments
- Saga state → PostgreSQL: persists saga state