Solution/aditya dolui - #99
Open
AdityaDolui wants to merge 4 commits into
Open
Conversation
This document outlines the design for a wallet-to-wallet transfer service, detailing problem statements, key design decisions, and architectural considerations.
Refactor design document for clarity and consistency, including updates to formatting, terminology, and structure.
Refactor design document to clarify objectives and strategies.
There was a problem hiding this comment.
Pull request overview
Adds a DESIGN_DOC.md describing the intended architecture and data model for a wallet-to-wallet transfer service (idempotency, concurrency control, and double-entry ledger).
Changes:
- Added a design document covering idempotency strategy, concurrency approach, and ledger invariants.
- Documented proposed database tables/relationships and class responsibilities.
Comment on lines
+1
to
+5
| # Wallet Transfer Service - Design Document | ||
|
|
||
| ## Problem Statement | ||
|
|
||
| The objective of this service is to implement a wallet-to-wallet transfer system that guarantees: |
Comment on lines
+16
to
+20
| --- | ||
|
|
||
| # Key Design Decisions | ||
|
|
||
| Before implementation, the following architectural decisions were made. |
Comment on lines
+74
to
+78
| --- | ||
|
|
||
| # Architecture | ||
|
|
||
| ```text |
Comment on lines
+92
to
+96
| --- | ||
|
|
||
| # Design Patterns Used | ||
|
|
||
| ## Repository Pattern |
Comment on lines
+167
to
+171
| --- | ||
|
|
||
| # Database Design | ||
|
|
||
| ## wallets |
Comment on lines
+231
to
+235
| --- | ||
|
|
||
| # Database Relationships | ||
|
|
||
| ```text |
Comment on lines
+249
to
+253
| --- | ||
|
|
||
| # Class Responsibilities | ||
|
|
||
| ## TransferController |
Comment on lines
+288
to
+292
| --- | ||
|
|
||
| # SOLID Principles Applied | ||
|
|
||
| ## Single Responsibility Principle |
Comment on lines
+316
to
+320
| --- | ||
|
|
||
| # Future Improvements | ||
|
|
||
| Potential enhancements: |
Comment on lines
+304
to
+305
| ## Open Closed Principle | ||
|
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Wallet Transfer Service
Summary
Implemented a wallet-to-wallet transfer service with strong transactional guarantees.
The service ensures:
Idempotent request processing
Safe concurrent execution
Double-entry ledger consistency
Atomic transaction processing
Retry-safe behavior
Transfer state management
Database Schema
Introduced the following tables:
wallets
Stores wallet balances and represents the current state of each wallet.
transfers
Stores business transaction information and tracks the lifecycle of a transfer.
ledger_entries
Stores immutable accounting records used for auditability and reconciliation.
idempotency_records
Stores request fingerprints and cached responses to guarantee idempotent behavior.
The schema enforces referential integrity using foreign key constraints and supports financial auditability through a double-entry ledger model.
Idempotency Strategy
A dedicated
idempotency_recordstable is used to handle duplicate requests safely.For every incoming request:
A SHA-256 request hash is generated.
The system checks whether the idempotency key already exists.
If the key exists and the request hash matches:
The previously stored response is returned.
If the key exists but the request hash differs:
The request is rejected with a conflict response.
If the key does not exist:
A new transfer is processed and the response is stored.
This guarantees retry-safe behavior and prevents duplicate transfers.
Concurrency Strategy
Concurrency is handled using:
PESSIMISTIC_WRITErow-level lockingDeterministic wallet lock ordering
Retry mechanism for lock acquisition failures
Deadlock Prevention
Before acquiring locks, wallet identifiers are sorted and always locked in a deterministic order.
Example:
Wallet A → Wallet B
instead of
Wallet B → Wallet A
This significantly reduces deadlock risk by preventing circular wait conditions.
Double Spending Protection
Wallet rows are locked before balance validation and updates occur.
This ensures that concurrent requests cannot spend the same balance simultaneously.
Database Consistency
The service follows a double-entry ledger model.
For every successful transfer:
One DEBIT ledger entry is created for the source wallet.
One CREDIT ledger entry is created for the destination wallet.
Example:
Transfer Amount = 100
Wallet | Entry Type | Amount -- | -- | -- Source Wallet | DEBIT | 100 Destination Wallet | CREDIT | 100This guarantees:
Complete auditability
Historical traceability
Ledger consistency
Design Patterns Used
Repository Pattern
Used for data access abstraction.
Repositories:
WalletRepository
TransferRepository
LedgerEntryRepository
IdempotencyRecordRepository
Factory Pattern
Used through
LedgerEntryFactory.Responsibilities:
Create debit ledger entries
Create credit ledger entries
Domain Service Pattern
Used through
TransferDomainService.Responsibilities:
Balance validation
Wallet debit
Wallet credit
Ledger generation
Transfer state transitions
DTO Pattern
Used to separate API contracts from domain entities.
DTOs:
TransferRequest
TransferResponse
ErrorResponse
State Transition Pattern
Implemented inside the
Transferentity through:markProcessed()markFailed()This prevents invalid status transitions.
Additional Notes
Implemented:
Global exception handling
Request hashing using SHA-256
Idempotency conflict detection
Transaction management using Spring Transactions
Retry support using Spring Retry
MapStruct-based DTO mapping
Clean layered architecture
SOLID design principles
Testing
Covered scenarios include:
Successful transfer execution
Insufficient balance validation
Idempotency replay
Idempotency conflict detection
Double-entry ledger verification
Concurrent transfer execution
Deadlock prevention validation
Documentation
Additional implementation details are available in:
DESIGN_DOC.mdIncluding:
Architecture overview
Database design
Class responsibilities
Concurrency strategy
Idempotency strategy
Future improvements