Featured Module - Backend Documentation

1. Backend Scope and Boundaries

Featured backend manages curated product placement records, activation windows, and customer-facing featured listing. It does not own product core lifecycle.

2. Module Composition (Aggregate + Leaf)

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

3. Data Model (Drizzle / PostgreSQL)

Primary table:

• featured_product (packages/db/src/schema/catalog/featured-product.ts)

Key schema traits:

• productId FK -> product.id (ON DELETE CASCADE)
• optional categoryId FK -> category.id (ON DELETE SET NULL)
• DB check constraint enforces valid date windows
• indexed columns: productId, categoryId, order, isActive, startDate/endDate

4. Runtime Rules and Domain Invariants

• Service-level date rule mirrors DB check: startDate <= endDate.
• Optional category must exist when provided.
• Customer read applies active + date-window filters.
• reorder(ids) exists at service level but has no exposed admin route in current controller.

5. Caching Strategy

Customer cache keyspace:

• catalog:featured:list:

Customer TTL resolution:

• CATALOG_FEATURED_CACHE_TTL_SECONDS
• fallback CATALOG_CACHE_TTL_SECONDS
• fallback REDIS_CACHE_TTL_SECONDS

Admin invalidation prefixes:

• catalog:featured:active*
• catalog:featured:list:*

6. Rate Limiting Strategy

No explicit featured-specific rate limiter is implemented for these controllers.

7. Error and Resilience Contracts

Primary error codes:

• FEATURED_NOT_FOUND
• FEATURED_INVALID_DATE_RANGE
• FEATURED_INVALID_SORT
• CATEGORY_NOT_FOUND

Service methods validate invariants before writes and use structured exceptions with errorCode.

8. Performance Notes

• Date/active filtering aligns with indexed query columns.
• Customer list reads are cache-backed with deterministic key segments.
• Pagination uses PaginationUtil.getDrizzleParams(...).

9. Backend Diagram

10. Release/QA Checklist

• Validate create/update date-window validation.
• Validate optional category validation and error mapping.
• Validate customer list active-window filtering.
• Validate cache invalidation on admin writes.
• Validate all exposed routes under Featured_* permissions.

11. File Map

---

12. Environment Variables

---

See Also

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