Category Module - Backend Documentation

1. Backend Scope and Boundaries

Category backend handles category hierarchy, visibility, slug history, and customer-facing category discovery. It does not manage product pricing/checkout logic.

2. Module Composition (Aggregate + Leaf)

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

3. Data Model (Drizzle / PostgreSQL)

Primary tables:

• category (packages/db/src/schema/catalog/category.ts)
• category_slug_history (packages/db/src/schema/catalog/category-slug-history.ts)

Notable schema traits:

• self-referential FK category.parent_id -> category.id with ON DELETE SET NULL
• depth/hierarchy enforced at service layer
• slug history table stores immutable old slugs with unique index
• category search indexes include trigram index on name

4. Runtime Rules and Domain Invariants

• Max category depth is 3.
• Parent category must exist.
• Self-parent and descendant-loop moves are invalid.
• Reorder payload IDs must be unique and all present.
• Delete is blocked if category has children.
• Slug changes insert into category_slug_history with conflict-safe behavior.

5. Caching Strategy

Customer cache keyspaces:

• catalog:categories:list:
• catalog:category:slug:

Customer TTL resolution:

• CATALOG_CATEGORY_CACHE_TTL_SECONDS
• fallback CATALOG_CACHE_TTL_SECONDS
• fallback REDIS_CACHE_TTL_SECONDS

Admin invalidation prefixes:

• catalog:categories:visible*
• catalog:categories:list:*
• catalog:category:slug:*

6. Rate Limiting Strategy

No explicit category-specific rate limiter is implemented in admin or customer category controllers.

7. Error and Resilience Contracts

Primary error codes:

• CATEGORY_NOT_FOUND
• CATEGORY_SELF_PARENT
• CATEGORY_MOVE_TO_DESCENDANT
• CATEGORY_MISSING_PARENT
• CATEGORY_DEPTH_EXCEEDED
• CATEGORY_HAS_CHILDREN
• CATEGORY_DUPLICATE_IDS
• CATEGORY_INVALID_SORT

Customer cache reads are resilient through Redis cache service getOrSet(...) fallback to DB loader.

8. Performance Notes

• Category list/detail reads are cache-backed.
• Query paths use indexed columns: parentId, isVisible, slug, order.
• Pagination is optional for customer flows and standard for admin flows.

9. Backend Diagram

10. Release/QA Checklist

• Validate hierarchy guards (self-parent, descendant, max depth, missing parent).
• Validate reorder transaction and duplicate-ID rejection.
• Validate slug-history resolution for old URLs.
• Validate visibility behavior for customer/mobile queries.
• Validate cache invalidation after admin writes.

11. File Map

---

12. Environment Variables

---

See Also

• Feature Guide: See Category Module - Feature List Section 6 (State Models) for category hierarchy diagrams.
• API Reference: See Category Module - API & Integration Guide Section 7 (Endpoint Reference + Payload Cheatsheet) for API contracts.