Cart Module - Backend Documentation

Audience: Backend developers, system architects Scope: Hybrid cart model, eligibility rules, coupon integration, and cache/runtime behavior.

1. Model Summary (Hybrid: Physical + Legacy Digital)

Cart supports physical product commerce with limited legacy digital compatibility.

• Cart-eligible physical product types: thangka, singing_bowl, statue, jewellery
• Cart checkout is online-only
• Delivery fee is removed from cart model and calculations

2. Schema Overview

2.1 Tables

cart

• Fields: id, user_id, status, applied_promotion_id, applied_promotion_code, applied_discount, created_at, updated_at
• Indexes:
  • cart_user_id_idx
  • cart_status_idx
  • cart_applied_promotion_id_idx
  • cart_one_active_per_user (partial unique index on user_id where status='active')
• Constraints:
  • cart_applied_discount_non_negative (applied_discount IS NULL OR applied_discount >= 0)

cart_item

• Fields: id, cart_id, product_id, unit_mrp, unit_sp, created_at, updated_at
• Indexes/constraints:
  • cart_item_cart_id_idx
  • cart_item_product_id_idx
  • cart_item_cart_product_idx (unique on cart_id + product_id)
  • product_id is NOT NULL
  • cart_item_unit_mrp_non_negative (unit_mrp >= 0)
  • cart_item_unit_sp_non_negative (unit_sp >= 0)

2.2 Enums

2.3 Removed from cart domain

• legacy cart payment-method projection fields

2.4 Drizzle source of truth

• packages/db/src/schema/cart/cart.ts
• packages/db/src/schema/cart/enums.ts

3. Eligibility Rules

Source: apps/api/src/modules/cart/customer/cart-customer.service.ts

• Allowed cart product types are resolved via helper functions in apps/api/src/common/utils/product.util.ts.
• If product type is digital and not legacy-allowed, service returns:
• For any other non-cart type, service returns:
  • CART_PRODUCT_NOT_ELIGIBLE

4. Service Behavior

4.1 CartCustomerService

Core methods:

• getCart
• addItem
• removeItem
• clearCart
• applyCoupon
• removeCoupon

Key behavior:

• Multi-step writes use DB transactions.
• addItem throws CART_PRODUCT_ALREADY_IN_CART if product already exists in cart.
• Cart reads use cache-aside with deterministic key construction.
• Coupon discount is applied through cart fields: appliedPromotionId, appliedPromotionCode, appliedDiscount.
• finalPayable = totalSp - (appliedDiscount ?? 0).

4.2 CartAdminService

Core methods:

• getUserCart

Key behavior:

• Provides support/debug read of a user's current active cart with items.

5. API Routes

5.1 Admin

• /api/admin/cart/users/:userId (GET)

5.2 Customer

• /api/cart (GET, DELETE)
• /api/cart/items (POST)
• /api/cart/items/:itemId (DELETE)

5.3 Mobile-composed customer

• /api/mobile/cart (GET, DELETE)
• /api/mobile/cart/items (POST)
• /api/mobile/cart/items/:itemId (DELETE)

5.4 Order handoff endpoints for payment initiation

Cart payment initiation is owned by order customer endpoints:

• /api/orders/checkout
• /api/orders/buy-now
• /api/mobile/orders/checkout
• /api/mobile/orders/buy-now

6. Caching Strategy

Implementation notes:

• Keys are built with CacheKeyUtil.build(...).
• Invalidation uses prefix patterns via invalidatePattern(prefix*).
• Redis failures degrade gracefully (warn + DB path).

7. Error Contracts

Enrollment records are finalized to enrolled after successful payment processing in order workflow.

9. Related Payment Docs

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

10. Backend Diagram

11. Module Composition

• CartModule - shared module
  • imports: ConfigModule, DatabaseModule, RedisModule
• CartCustomerModule - customer leaf
  • controller: CartCustomerController
  • service: CartCustomerService
• CartAdminModule - admin leaf
  • controller: CartAdminController (debug only)

12. File Map

---

13. Environment Variables

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

---

See Also

• Feature Guide: See Cart - Feature List Section 6 (State Models) for cart state diagram.
• API Reference: See Cart - API & Integration Guide Section 7 (Endpoint Reference + Payload Cheatsheet) for API contracts.