Tag Module - Backend Documentation

1. Backend Scope and Boundaries

Tag backend manages taxonomy labels, slug history, and public tag discovery endpoints. It does not own product assignment logic beyond validating referenced tag IDs in related modules.

2. Module Composition (Aggregate + Leaf)

• Aggregate admin composition: apps/api/src/modules/catalog/catalog-admin.module.ts
  • Includes TagAdminModule
• Leaf admin module: apps/api/src/modules/catalog/admin/tag/tag-admin.module.ts
• Leaf customer module: apps/api/src/modules/catalog/customer/tag/tag-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:

• tag (packages/db/src/schema/catalog/tag.ts)
• tag_slug_history (packages/db/src/schema/catalog/tag-slug-history.ts)

Notable schema traits:

• tag.type uses tag_type enum
• unique constraints on tag.slug and tag.name
• slug history table stores immutable old slugs with unique index

4. Runtime Rules and Domain Invariants

• Tag name must be unique at create/update time.
• Slug generation is deterministic and conflict-safe.
• Slug-history rows are inserted on slug changes (onConflictDoNothing).
• Customer sort fields are constrained to explicit allowlist.

5. Caching Strategy

Customer cache keyspaces:

• catalog:tags:list:
• catalog:tag:slug:

Customer TTL resolution:

• CATALOG_TAG_CACHE_TTL_SECONDS
• fallback CATALOG_CACHE_TTL_SECONDS
• fallback REDIS_CACHE_TTL_SECONDS

Admin invalidation prefixes:

• catalog:tags:list:*
• catalog:tag:slug:*

6. Rate Limiting Strategy

No explicit tag-specific rate limiter is implemented in tag controllers for this scope.

7. Error and Resilience Contracts

Primary error codes:

• TAG_NOT_FOUND
• TAG_NAME_EXISTS
• TAG_INVALID_SORT

Admin delete path logs a warning that product-tag usage checks are not yet enforced in this service path.

8. Performance Notes

• Query paths rely on indexed name/type columns and pagination utilities.
• Customer reads are cache-backed via Redis getOrSet(...).
• Search paths use ILIKE conditions on name and slug.

9. Backend Diagram

10. Release/QA Checklist

• Validate duplicate-name conflict logic on create/update.
• Validate slug-history capture and old-slug resolution.
• Validate customer sort/type filtering behavior.
• Validate cache invalidation after admin writes.
• Validate permission coverage for Tags_* endpoints.

11. File Map

---

12. Environment Variables

---

See Also

• Feature Guide: See Tag Module - Feature List Section 6 (State Models) for tag type diagrams and lifecycle states.
• API Reference: See Tag Module - API & Integration Guide Section 7 (Endpoint Reference + Payload Cheatsheet) for API contracts.