Payment Wallet System (Backend-Only, System Design Project)

1. Introduction

This project is a backend-only Payment Wallet System designed using real-world financial system principles.
It demonstrates how digital wallet systems work internally, focusing on correctness, consistency, concurrency handling, and transaction safety.

The project intentionally avoids frontend development to concentrate on backend engineering and system design.

---

2. Real-World Usage

Systems like Google Pay, PhonePe, Paytm, Amazon Pay, Uber Wallet, and banking platforms use similar backend architectures.

Whenever a user:

• Adds money
• Transfers money
• Receives cashback
• Gets a refund

A wallet backend system like this is involved.

---

3. Problem Statement

Handling money is not simple CRUD.

Incorrect implementations can lead to:

• Money duplication
• Money loss
• Incorrect balances
• Inconsistent transaction history
• Race conditions under concurrent requests

This project solves these issues using proper system design techniques.

---

4. Design Goals

The main goals of this project are:

• Ensure no money is lost or created
• Maintain strong data consistency
• Handle concurrent transactions safely
• Provide a full audit trail
• Build a scalable backend architecture

---

5. High-Level Architecture

The system is divided into the following layers:

1. API Layer

   • Exposes REST APIs using Express.js
   • Handles routing, validation, and authentication

2. Service Layer

   • Contains core business logic
   • Manages transactions and consistency

3. Database Layer (PostgreSQL)

   • Provides ACID guarantees
   • Uses row-level locking
   • Stores immutable ledger records

4. Future Infrastructure (Optional)

   • Redis for idempotency
   • Queues for async processing
   • Monitoring and metrics

---

6. Core Design Principles

6.1 Double-Entry Ledger System

Every financial transaction creates two ledger entries:

• One debit entry (negative amount)
• One credit entry (positive amount)

Example: User A sends ₹500 to User B

User A ledger entry: -500
User B ledger entry: +500

This ensures:

• Total money in the system remains constant
• Every transaction is auditable
• Errors can be traced easily

This approach is used by banks and fintech companies.

---

6.2 Atomic Transactions

All operations related to a money transfer are executed inside a single database transaction.

If any step fails, the entire transaction is rolled back.
This guarantees all-or-nothing behavior.

---

6.3 Concurrency Safety

To prevent race conditions:

• Wallet rows are locked using row-level locks
• Concurrent transfers from the same wallet are serialized safely

---

6.4 Balance Is Not the Source of Truth

• Ledger entries are the source of truth
• Wallet balance is a cached value for faster reads

Balances can always be recomputed from ledger entries if required.

---

7. Money Transfer Flow

The money transfer process works as follows:

1. Client sends a transfer request
2. Backend validates sender and receiver
3. Database transaction begins
4. Sender wallet row is locked
5. Balance is checked
6. Sender wallet is debited
7. Receiver wallet is credited
8. Two ledger entries are inserted
9. Transaction is committed

If any step fails, the transaction is rolled back.

---

8. Database Design

The database consists of three core tables:

1. users

   • Stores user identity information

2. wallets

   • Stores wallet balance for fast access

3. ledger_entries

   • Stores immutable transaction records

Ledger entries are never updated or deleted.

---

9. Technology Stack

Backend: Node.js with Express
Database: PostgreSQL
Authentication: JWT
Database Access: Raw SQL
Testing: Postman
Version Control: Git

---

10. Project Folder Structure

wallet-system/ ├── src/ │ ├── app.js │ ├── server.js │ ├── config/ │ │ └── db.js │ ├── routes/ │ │ ├── auth.routes.js │ │ └── wallet.routes.js │ ├── controllers/ │ │ ├── auth.controller.js │ │ └── wallet.controller.js │ ├── services/ │ │ └── wallet.service.js │ ├── models/ │ │ ├── user.model.js │ │ ├── wallet.model.js │ │ └── ledger.model.js │ ├── middlewares/ │ │ └── auth.middleware.js │ ├── utils/ │ │ └── dbTransaction.js │ └── sql/ │ └── schema.sql ├── README.md ├── package.json └── .gitignore

---

11. API Endpoints

Authentication: POST /auth/register
POST /auth/login

Wallet: POST /wallet/create
POST /wallet/add-money
POST /wallet/transfer
GET /wallet/balance
GET /wallet/transactions

---

12. Failure Handling

• Insufficient balance → request rejected
• Concurrent transfers → handled via row locks
• Partial failures → full rollback
• Duplicate requests → prevented via idempotency (future scope)

---

13. Scalability Considerations

• Stateless backend services
• Horizontal scaling
• Database row-level locking
• Read replicas for transaction history
• Redis for idempotency and caching
• Async processing for notifications

---

14. Testing Strategy

• API testing using Postman
• Manual SQL verification
• Edge case testing:
  • Concurrent transfers
  • Insufficient balance
  • Duplicate requests

---

15. Future Enhancements

• Idempotency keys using Redis
• Async notifications
• Rate limiting
• Monitoring and metrics
• Admin reconciliation tools

---

Note: This README is intentionally detailed so that any developer or AI assistant can understand the system design and help implement the project correctly without additional explanation.