Catalog Product - Backend Documentation

1. Backend Scope and Boundaries

The product backend owns catalog product lifecycle, slug continuity, product-tag linking, and customer product reads. It does not own checkout/order payment orchestration, but it provides pricing and sellability source-of-truth used by those modules.

2. Module Composition (Aggregate + Leaf)

• Aggregate admin composition: apps/api/src/modules/catalog/catalog-admin.module.ts
  • Includes ProductAdminModule
• Leaf admin module: apps/api/src/modules/catalog/admin/product/product-admin.module.ts
• Leaf customer module: apps/api/src/modules/catalog/customer/product/product-customer.module.ts
• Mobile composition: apps/api/src/modules/mobile/mobile.module.ts mounts customer module under /mobile.

3. Data Model (Drizzle / PostgreSQL)

Primary tables and joins:

• product (packages/db/src/schema/product/product.ts)
• product_slug_history (packages/db/src/schema/product/product-slug-history.ts)
• product_tag join (packages/db/src/schema/product/product-tag.ts)
• Related lookup tables: category, tag, featured_product

Key constraints/indexes used by runtime:

• product.slug unique
• product.product_type is physical-only: thangka, singing_bowl, statue, jewellery
• product_tag composite primary key (product_id, tag_id)
• money columns mrp and sp are integer paisa
• trigram indexes on product.title and product.description

Physical-detail columns on product:

• delivery (text, required)
• materials (jsonb string array, required)
• certificate (varchar, required)
• is_master_grade (boolean, required, default false)
• is_best_seller (boolean, required, default false)
• size (jsonb object, required; shape depends on product type)

4. Runtime Rules and Domain Invariants

• sp cannot exceed mrp.
• Physical detail fields (delivery, materials, certificate, size) are required on create.
• size shape must match productType:
  • thangka -> rectangular
  • singing_bowl -> radius
  • statue -> radius
  • jewellery -> circumference
• Status transitions are constrained:
  • draft -> published
  • published -> unlisted
  • unlisted -> archived
• Customer list/detail include only published and isSellable=true products.
• Slug uniqueness check includes both current products and slug-history rows.
• Multi-table writes (product + slug history + product_tag) are transaction-wrapped.

5. Caching Strategy

Customer read cache keyspaces:

• catalog:products:list:
• catalog:product:slug:
• catalog:products:featured:

All keys use CacheKeyUtil.build(...) with deterministic segments.

Admin write invalidation uses prefix patterns via invalidatePattern(...) for all above keyspaces.

6. Rate Limiting Strategy

Redis sorted-set sliding-window limiter is implemented in controllers for list/search endpoints:

• Admin list route limiter key prefix: rl:catalog:admin:products:search:
• Customer list route limiter key prefix: rl:catalog:customer:products:search:
• Exceed path throws RateLimitExceededException.

7. Error and Resilience Contracts

Primary error codes:

• PRODUCT_NOT_FOUND
• PRODUCT_CREATE_FAILED
• PRODUCT_CATEGORY_NOT_FOUND
• PRODUCT_TAG_NOT_FOUND
• PRODUCT_SP_EXCEEDS_MRP
• PRODUCT_INVALID_STATUS_TRANSITION
• PRODUCT_INVALID_SORT
• RATE_LIMIT_EXCEEDED

Redis read/write/cache-invalidation failures are logged and gracefully fall back to DB reads where implemented.

8. Performance Notes

• List queries use projection selects instead of loading full rows.
• Search combines trigram similarity + ILIKE with escaped patterns.
• Pagination uses PaginationUtil.getDrizzleParams(...).
• Count queries are executed in parallel with list query on customer list paths.

9. Backend Diagram

10. Release/QA Checklist

• Validate CRUD and permission gates for Products_*.
• Validate slug-history insertion and old-slug resolution.
• Validate rate-limiter thresholds through env values.
• Validate cache invalidation for create/update/delete.
• Validate transaction integrity for product + tags + slug-history updates.

11. File Map

---

12. Environment Variables

---

See Also

• Feature Guide: See Catalog Product - Feature List Section 6 (State Models) for product lifecycle diagrams and status transitions.
• API Reference: See Catalog Product - API & Integration Guide Section 7 (Endpoint Reference + Payload Cheatsheet) for API contracts.