Technical Design Specification
Wallet Module
WALLET
1. Introduction
1.1 Purpose
This document provides the technical design specification for the Wallet module. It describes the system architecture, service design, data models, and integration patterns required to implement the electronic wallet functionality.
1.2 Scope
The Wallet module implements electronic wallet operations including balance management, deposits, withdrawals, transfers, and payments for recruitment services. It integrates with the AUTH module for user authentication and the RECR module for service payments.
1.3 Design Decisions
| Decision | Rationale | Requirement |
|---|
| Use PostgreSQL for wallet data | ACID compliance required for financial transactions | NFR-007 |
| PIN-based transaction authorization | Balance security without full auth flow | NFR-005 |
| Optimistic locking for balance updates | Prevent race conditions in concurrent transactions | NFR-003 |
| Separate payout request workflow | Admin approval required for withdrawals | FR-015 |
| RabbitMQ for inter-service communication | Asynchronous event-driven architecture | NFR-001 |
2. Architecture
2.1 System Architecture
The Wallet module follows a service-oriented architecture with clear separation of concerns:
| Component | Responsibility | Technology |
|---|
| Wallet API | REST API endpoints for wallet operations | NestJS |
| Wallet Service | Business logic for wallet management | NestJS Service |
| Transaction Service | Transaction processing and audit trail | NestJS Service |
| Payment Service | Payment order management | NestJS Service |
| Payment Gateway Adapter | Integration with external PG | NestJS Module |
| Message Producer | Event publishing to RabbitMQ | amqplib |
| Database | Persistent storage for wallet data | PostgreSQL + Drizzle ORM |
2.2 Component Diagram
Figure 1: Wallet Component Diagram
3. Technical Design
3.1 Wallet Management Service
| Aspect | Design |
|---|
| Resolves | FR-001, FR-002, FR-003 |
| Class | WalletService |
| Dependencies | Drizzle ORM, AuthGuard, MessageProducer |
Methods:
| Method | Description | Returns |
|---|
| createWallet(userId) | Creates wallet for new user | Wallet |
| getBalance(userId) | Returns wallet balance and status | WalletBalance |
| setPin(userId, pin) | Hashes and stores wallet PIN | void |
| verifyPin(userId, pin) | Verifies wallet PIN | boolean |
| freezeWallet(walletId) | Freezes wallet for admin action | Wallet |
3.2 Transaction Service
| Aspect | Design |
|---|
| Resolves | FR-004, FR-009, FR-010 |
| Class | TransactionService |
Methods:
| Method | Description | Returns |
|---|
| createTransaction(data) | Creates transaction record with balance snapshot | Transaction |
| getTransactions(walletId, filters) | Returns paginated transaction history | PaginatedResult |
| getTransactionById(id) | Returns single transaction details | Transaction |
3.3 Payment Service
| Aspect | Design |
|---|
| Resolves | FR-011, FR-012, FR-013 |
| Class | PaymentService |
Methods:
| Method | Description | Returns |
|---|
| createPaymentOrder(data) | Creates payment order for service | PaymentOrder |
| processPayment(orderId, pin) | Processes payment from wallet balance | PaymentResult |
| processRefund(orderId) | Processes refund to wallet | RefundResult |
3.4 Withdrawal Service
| Aspect | Design |
|---|
| Resolves | FR-007, FR-015 |
| Class | WithdrawalService |
Methods:
| Method | Description | Returns |
|---|
| createPayoutRequest(data) | Creates withdrawal request | PayoutRequest |
| approvePayout(requestId, adminId) | Approves withdrawal request | PayoutRequest |
| rejectPayout(requestId, adminId, reason) | Rejects withdrawal request | PayoutRequest |
| processPayout(requestId) | Processes approved payout to bank | PayoutResult |
3.5 Transfer Service
| Aspect | Design |
|---|
| Resolves | FR-008 |
| Class | TransferService |
Methods:
| Method | Description | Returns |
|---|
| transfer(senderId, recipientId, amount) | Transfers funds between wallets | TransferResult |
3.6 Payment Gateway Integration
| Aspect | Design |
|---|
| Resolves | FR-006 |
| Class | PaymentGatewayAdapter |
Methods:
| Method | Description | Returns |
|---|
| initiatePayment(data) | Creates payment session with PG | PaymentSession |
| verifyPayment(transactionId) | Verifies payment status with PG | PaymentStatus |
| processWebhook(payload) | Handles PG webhook callback | WebhookResult |
4. Data Design
4.1 Database Schema
Figure 2: Wallet Database Schema
5. Integration Design
5.1 Sequence Diagram
Figure 3: Wallet Integration Flow
6. Security Design
| Security Measure | Implementation | Requirement |
|---|
| Authentication | JWT token validation via AUTH service | NFR-005 |
| Authorization | Role-based access control (User, Admin) | NFR-005 |
| PIN Security | bcrypt hashing, 6-digit format | NFR-005 |
| Data Encryption | AES-256 for sensitive fields (account numbers) | NFR-006 |
| Audit Trail | Complete transaction history with timestamps | NFR-007 |
7. Requirements Traceability
| SRS Requirement |
TDS Section |
Component |
DB Table |
| FR-001: Create Wallet | 3.1 | WalletService | wallet_wallets |
| FR-002: View Balance | 3.1 | WalletService | wallet_wallets |
| FR-003: Set PIN | 3.1 | WalletService | wallet_wallets |
| FR-004: Transaction History | 3.2 | TransactionService | wallet_transactions |
| FR-005: Payment Methods | 3.3 | PaymentService | wallet_payment_methods |
| FR-006: Deposit Funds | 3.6 | PaymentGatewayAdapter | wallet_transactions |
| FR-007: Withdrawal | 3.4 | WithdrawalService | wallet_payout_requests |
| FR-008: Transfer | 3.5 | TransferService | wallet_transactions |
| FR-011: Pay Job Posting | 3.3 | PaymentService | wallet_payment_orders |
| FR-015: Admin Approval | 3.4 | WithdrawalService | wallet_payout_requests |
