Cart Module - Feature List

1. Overview

Cart supports both digital and physical products.

• Physical product types: thangka, singing_bowl, statue, jewellery
• Online-only checkout integration
• No delivery fee in cart totals

2. Exposed Routes

3. Core Features

Cart integrity is DB-hardened:

• cart_item.product_id cannot be null
• cart.applied_discount cannot be negative
• cart_item.unit_mrp and cart_item.unit_sp cannot be negative

4. State Models

4.1 Cart lifecycle state

4.2 Cart item lifecycle

5. Queue/Worker Features

6. Admin Features

7. Customer Features

Notes:

• Customer surface is authenticated (JwtAuthGuard) and mounted under /api/mobile/cart via MobileModule composition.
• buyNow behavior exists in CartCustomerService for internal service use; public buy-now API is owned by order endpoints.

8. Cache Features

• Keys are built with CacheKeyUtil.build(...)
• Values are invalidated by prefix with invalidatePattern(prefix*)
• Redis failures degrade gracefully (warn + DB fallback)

9. Rate Limiting

Redis sliding-window counters:

• customer mutating cart operations

Failures in Redis rate checks are fail-open with warning logs.

10. Integration Boundaries

• Cart writes and reads stay in cart services and schema (cart, cart_item).
• Checkout and buy-now payment initiation are owned by order customer endpoints.
• Async cart clearing after confirmed order is handled through cart queue job cart.clear_after_order_confirmed.

Related payment docs:

• apps/fumadocs/content/docs/developer/payment/cart-checkout-flow.mdx

11. Environment Variables

• CART_CUSTOMER_OPERATION_RATE_LIMIT (default 60)
• CART_CUSTOMER_RATE_WINDOW_SECONDS (default 60)
• CART_CUSTOMER_CACHE_TTL_SECONDS (default 60)
• CART_EXPIRE_INTERVAL_MS (default 600000)

12. Error UX Mapping

13. Release/QA Checklist

• Verify cart creates lazily on first GET request for authenticated user
• Verify duplicate product add returns 409 and does not create duplicate item
• Verify coupon application and removal work correctly
• Verify cart invalidation on write operations
• Verify rate limiting returns 429 on threshold breach
• Verify mobile routes /api/mobile/cart/* work correctly
• Verify cart clear after order payment success
• Verify Redis fallback on cache failures

14. Data Flow

15. Integration Flows

15.1 Add to Cart Flow

A customer adds a sellable product to their active cart.

1. Customer calls GET /api/cart (or GET /api/mobile/cart) to get or create their active cart.
2. Customer calls POST /api/cart/items (or POST /api/mobile/cart/items) with { productId, quantity }.
3. System validates product is not already in cart (returns 409 if duplicate).
4. System inserts cart_item with snapshot pricing (unitMrp, unitSp).
5. System updates cart totals: recalculate totalMrp, totalSp, apply any existing appliedDiscount.
6. System invalidates Redis cache key cart:user:{userId}.
7. Client refetches cart to see updated totals and item.

15.2 Checkout Flow

A customer proceeds from cart to order checkout.

1. Customer has items in active cart with valid coupon (if any applied).
2. Customer calls POST /api/orders/checkout with idempotency-key header.
3. Order service validates cart exists, is active, has items, and coupon is still valid.
4. Order service creates order, snapshots pricing, applies discount, sets status payment_pending.
5. Order service enqueues cart.clear_after_order_confirmed job to run after payment success.
6. Payment gateway is invoked, returns initiationType with gatewayPayload.
7. Customer completes payment via form_post or redirect.
8. Payment callback triggers order payment success, which triggers cart clear job.
9. CartProcessor clears the user's active cart and sets status to completed.

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

---

See Also

• API Reference: See Cart - API & Integration Guide Section 7 (Endpoint Reference + Payload Cheatsheet) for complete request/response DTOs.
• Backend Reference: See Cart - Backend Documentation Section 3 (Data Model) for schema details.