team Minutemaid

[MdNaqui4]

Feature: Persistent Shopping Cart, Atomic Checkout & Live Simulator Dashboard using Valkey
📝 Overview
This pull request introduces a highly scalable and thread-safe persistent shopping cart and checkout subsystem built with Fast API on the backend and React on the frontend, fully powered by Valkey as the fast, multi-model storage layer.

To assist with evaluation, we have also created a beautiful Live Simulation Dashboard directly integrated into the React application, which allows step-by-step walkthroughs of e-commerce lifecycles with real-time Valkey memory and TTL visualization.

---

Key Features Implemented

1. Persistent Shopping Cart (/api/cart)

• Uses Valkey Hashes (cart:{userId}) to persist user cart states globally.
• Features real-time stock-availability validations on addition/update.
• Supports Valkey Strings for coupon linkages and sets up automatic expirations (TTL) on user carts.

2. Atomic Inventory Reservation via Lua (/api/checkout/start)

• Avoids e-commerce overselling issues under heavy concurrent loads.
• Employs a thread-safe Lua Script (EVAL) to atomically check physical product stock and increment a reserved count in Valkey JSON (product:{id}).
• Establishes a temporary reservation lock key with a 10-minute expiry TTL (reservation:{orderId}:{productId} EX 600) to hold items during payment.

3. Idempotency Key Lock Protection

• Enforces strict API idempotency using the X-Idempotency-Key header on checkout.
• Employs Valkey SET NX EX (SET idempotency:{key} {orderId} NX EX 86400) to guarantee that double-clicked payments or re-transmissions return the cached order JSON structure immediately without double-booking inventory.

4. Interactive Live Simulation Console (/simulation)

• Features an inspectable e-commerce timeline (Auth -> Add to Cart -> Apply Coupon -> Lua Checkout -> Idempotency check -> Confirm).
• Shows live API payload requests and responses in an integrated terminal log.
• Displays a real-time Valkey Key-Value state tree that updates every 2 seconds, showing current database keys, values, and counting-down TTL locks (e.g. reservation expirations).

---

Valkey Command Coverage

The implementation covers a wide array of advanced Valkey data structures and commands:

• HSET, HGETALL, HDEL, HEXISTS**: Active shopping cart storage.
• JSON.SET, JSON.GET, JSON.NUMINCRBY**: Product catalog data, Coupon configurations, and Order structures.
• EVAL**: Atomic stock reservation script executing transactionally.
• SET ... NX EX**: Idempotency locks and temporary TTL reservations.
• SADD, SISMEMBER, SMEMBERS**: Coupon usage limits and unique user analytics tracking.
• ZADD, ZRANGE**: User order histories stored in a sorted set keyed by timestamp.

---

Verification & Run Instructions

1. Prerequisites (WSL / Docker)
   Run Valkey Bundle image inside your Docker container:

docker run -d --name valkey -p 6379:6379 valkey/valkey-bundle:9-alpine

2. Backend Setup

3. Move to backend folder: cd backend

4. Install dependencies: pip install -r requirements.txt

5. Run automated Pytest integration tests:

   pytest tests/test_cart_checkout.py -v

6. Start FastAPI server:

   python -m uvicorn app.main:app --reload --port 8000

7. Frontend Setup

8. Move to frontend folder: cd frontend

9. Start React app:

   npm start

10. Open http://localhost:3000/simulation to run the step-by-step interactive simulator console.