solution/sudhanshukroy

[SkroyCodes]

Summary

Implemented the core wallet-to-wallet transfer workflow.

The solution focuses on:

• Atomic transfer processing
• Retry-safe idempotency handling
• Correct debit and credit balance updates
• Double-entry ledger creation for successful transfers
• Failed transfer recording for expected business failures
• Concurrency-safe wallet updates
• Integration tests for success, failure, duplicate requests, and concurrent transfers

AI disclosure

Tool used: ChatGPT

How I used it:

I used ChatGPT as a planning, review, and implementation-support assistant.

I worked design-first. I first prepared the initial approach and decided the main direction of the solution myself: wallet-to-wallet transfer flow, idempotency handling, transaction boundaries, ledger entries, duplicate request handling, and failed transfer handling.

I used AI to improve clarity, validate edge cases, review clean service flow, identify error scenarios, generate/refine test cases based on my approach document, and improve documentation wording.

I did not use AI to blindly generate the full solution. I reviewed, corrected, implemented, ran, and verified the final solution locally.

Representative prompts and AI usage details are documented in AI_USAGE.md.

Schema Design

Introduced the following main entities/tables:

wallet

Stores wallet balance.

Important fields:

• wallet_id
• balance

transfer

Stores each transfer attempt and its lifecycle.

Important fields:

• transfer_id
• source_wallet_id
• destination_wallet_id
• amount
• status

Supported statuses:

• PENDING
• PROCESSED
• FAILED

Indexes are added on source and destination wallet references.

ledger_entry

Stores accounting entries for successful transfers.

Important fields:

• entry_id
• transfer_id
• wallet_id
• transaction_type
• amount

Supported transaction types:

• DEBIT
• CREDIT

For every successful transfer, two ledger entries are created: one debit entry for the source wallet and one credit entry for the destination wallet.

idempotency_record

Stores retry-safe request processing state.

Important fields:

• idempotency_record_id
• idempotency_key
• status
• transfer_id
• result_status
• result_message

The idempotency_key is unique, so the same request key cannot trigger the transfer logic more than once.

Idempotency Strategy

The service uses a separate idempotency_record table.

Flow:

1. A request comes with an idempotencyKey.
2. The service tries to claim the key.
3. If the key is new, the transfer flow proceeds.
4. If the key already exists, the transfer is not processed again.
5. The stored result/status is returned for duplicate requests.
6. Successful results and expected failed results are both stored against the idempotency key.

This prevents duplicate debit/credit operations during retries or duplicate delivery.

Concurrency Strategy

The implementation uses pessimistic row locking for involved wallets.

Both source and destination wallets are locked before balance validation and balance updates. Wallets are locked in wallet ID order to reduce deadlock risk.

This prevents race conditions where concurrent transfers from the same wallet could otherwise overdraw the source balance.

How to Run

Using Maven wrapper on Windows:

.\mvnw.cmd spring-boot:run

Using Maven wrapper on Linux/Mac:

./mvnw spring-boot:run

If Maven is installed globally:

mvn spring-boot:run

How to Test

Using Maven wrapper on Windows:

.\mvnw.cmd test

Using Maven wrapper on Linux/Mac:

./mvnw test

If Maven is installed globally:

mvn test

Test coverage includes:

• Successful wallet transfer
• Insufficient balance
• Invalid wallet scenario
• Duplicate idempotency key
• Ledger entry validation
• Concurrent transfer attempts from the same source wallet

Tradeoffs / Assumptions

• The service focuses on the core wallet transfer problem rather than extra read APIs.
• Expected business failures, such as insufficient balance, are recorded as failed transfer outcomes.
• Successful transfers create exactly two ledger entries.
• Duplicate idempotency keys return the stored result instead of reprocessing the transfer.
• Pessimistic locking is used for correctness under concurrent debit attempts.
• The implementation keeps the controller thin and places transfer orchestration in the service layer.

Checklist

• Tests pass
• README or notes updated
• PR description explains schema, idempotency, and concurrency
• AI usage documented

[Copilot]

Pull request overview

This PR adds initial planning documentation for the wallet transfer assignment, outlining the intended transactional flow (success/failure), proposed schema direction, idempotency/concurrency considerations, a testing plan, and an AI usage disclosure.

Changes:

• Added an initial end-to-end transfer workflow write-up (including failure handling) and proposed DB tables/indexes.
• Documented idempotency and concurrency concerns to guide the upcoming implementation.
• Added an AI usage note describing the tool and general usage.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 6 comments.

File	Description
APPROACH.md	New design/approach document covering transfer flows, schema direction, idempotency, concurrency, and testing.
AI_USAGE.md	New AI disclosure note describing the tool used and how it contributed to planning.