Design a digital game shop backend

Design the backend for a simple digital game shop where users can buy virtual items (e.g., games, in‑game currency, skins) using credits in their account. ### Functional requirements 1. **User credit (wallet)** - Each user has an account with a wallet balance in a single currency (e.g., EUR). - Users can **add credit** to their wallet (e.g., after successful payment with a card or external PSP). 2. **Purchase item** - A user can purchase one or more items from the shop. - The system must: - Check that the user has sufficient credit. - Deduct the correct amount from the user's wallet. - Grant the user ownership/entitlement of the purchased items. - The purchase should go through a **`PENDING` → `COMPLETED`** flow rather than directly `COMPLETED`. - In the purchase API, discuss whether the client should send: - `item_id` + `quantity` (and the server looks up prices), or - `total_amount` to charge (sent by the client), and justify your choice. 3. **Refund** - Support refunding a purchase (full or partial refund of items / amount). - Refunding should: - Return credits to the user's wallet. - Potentially revoke entitlements for refunded items (depending on business rules you can define). 4. **Failure scenarios** - Handle **duplicate client requests** (e.g., due to retries when the client times out) so that operations are **idempotent**. - Handle **server failure** in the middle of an operation (e.g., crash after debiting the wallet but before granting the item, or vice versa) using appropriate data modeling and database transactions. ### Non‑functional requirements (you may assume reasonable numbers) - Millions of users, with typical read/write traffic of an online store. - Strong consistency for money and entitlements: no user should be charged without getting the item, or get an item without being charged. - High availability is nice but correctness of balances and orders is more important. ### Tasks Design the system focusing on: 1. **High‑level architecture** - Roughly outline the services/components (e.g., User Service, Wallet Service, Order Service, Catalog Service) or a monolith if you prefer, and how they interact. 2. **APIs** Define REST‑style APIs (you can give example HTTP endpoints and JSON bodies) for at least: - `Add credit to user` (top up wallet) - `Create a purchase` (place an order for one or more items) - `Complete a purchase` (if you separate creation and payment) or a single `Purchase` endpoint that handles the full flow - `Refund` a purchase (full or partial) Be explicit about: - Request / response schemas. - What fields are client‑supplied vs server‑computed (e.g., whether the client sends `total_amount`). - How you represent `PENDING`, `COMPLETED`, `CANCELLED`, `REFUNDED` states. 3. **Data model** Propose a relational data model (tables/collections and key fields) for at least: - `User` - `Item` (or `Product`) - `Wallet` and/or `WalletTransaction` (ledger of credits/debits) - `Order` - `OrderItem` - Optionally `PaymentTransaction` and `Refund` Show how you keep a consistent wallet balance and item ownership. 4. **Transaction and consistency model** Explain: - How you will use **database transactions** to ensure that wallet balance updates and entitlements changes happen atomically for a purchase (or are rolled back together on error). - How the `PENDING` order status fits in (e.g., why it is better than going directly to `COMPLETED`). - What happens if the server crashes at each step of the purchase or refund flow, and how your design ensures that you can recover to a correct state (possibly using background jobs or retries). 5. **Idempotency and duplicate requests** - Show how you make operations like "add credit" and "purchase item" **idempotent** (e.g., via idempotency keys, request IDs, or unique constraints). - Describe what happens if the same request is replayed multiple times by the client or by the payment provider callback. 6. **Additional considerations (brief)** - Handling concurrent purchases from the same user. - Simple scaling strategy (read replicas, partitioning by user ID, etc.). - How you would log and audit financial and entitlement changes. Your answer should walk through the main flows: - Add credit to a user's account - Purchase an item - Refund an item and explain how your design meets the consistency, failure‑handling, and idempotency requirements.