Search Module - Backend Documentation

1. Architecture

Search behavior is implemented in existing product services.

• ProductAdminService.findAll
• ProductCustomerService.findAll

2. Database Support

• PostgreSQL pg_trgm extension
• Trigram indexes:
  • product_title_trgm_idx
  • product_description_trgm_idx
  • category_name_trgm_idx
  • tag_name_trgm_idx

3. Query Pattern

When search is provided:

• title/description ILIKE
• category and tag EXISTS clauses
• trigram threshold: similarity(product.title, :search) > SEARCH_SIMILARITY_THRESHOLD (default 0.3)
• optional relevance sorting: sort=relevance

4. Caching

• Admin product search: not cached
• Mobile product search: cache-aside (catalog:products:list:<segments>)

All key construction follows CacheKeyUtil.build(...) with deterministic ordered segments.

5. Rate Limiting

Controller-level Redis sliding window is applied on product list endpoints.

• admin products route
• mobile products route

Limiter failure is fail-open with warning logs.

6. Routes

/api/admin/products
/api/mobile/products

7. Operational Notes

• Keep select projections explicit
• Keep paginated list responses only
• Monitor trigram query plans for high-cardinality datasets

8. Reference Files

• apps/api/src/modules/catalog/admin/product/product-admin.controller.ts
• apps/api/src/modules/catalog/admin/product/product-admin.service.ts
• apps/api/src/modules/catalog/customer/product/product-customer.controller.ts
• apps/api/src/modules/catalog/customer/product/product-customer.service.ts
• packages/db/src/schema/product/product.ts

See Also

• Feature Guide: See Search - Feature List for feature details.
• API Reference: See Search - API & Integration Guide for API contracts.