Brand Series Module - Feature List

1. Feature Overview

Brand Series groups product collections within a brand for storefront merchandising. Each series belongs to exactly one brand and one category, and can be linked from individual products via a nullable foreign key.

The module follows a simple execution model:

• all operations are synchronous (no queue workers)
• admin surface provides full CRUD plus reorder
• customer/mobile surface provides visible-only listing and slug-based detail

The customer surface is public (no authentication required) and mounted through the shared mobile composition layer.

2. Route Ownership and Surfaces

Swagger tags used by brand series controllers:

• Brand Series (Admin)
• Brand Series

Customer/mobile routes are public (no JWT required) and filtered to visible series only.

3. Admin Feature Matrix

4. Customer/Mobile Feature Matrix

Notes:

• Customer list accepts optional brandId and categoryId query parameters to scope results.
• Mobile-composed equivalents are available at /api/mobile/brand-series/... via routing composition.
• Customer list and detail include resolved brandName, brandSlug, categoryName, and categorySlug for storefront rendering.
• Customer detail additionally includes productCount (count of published sellable products linked to the series).

5. Key Business Rules

• Series name must be unique within brand-category pair (enforced by DB unique constraint brand_series_brand_category_uidx).
• Slug is auto-generated from name and suffix-resolved on conflict (e.g. dell-laptops, dell-laptops-1, dell-laptops-2).
• Slug has a database-level unique constraint (brand_series_slug_uidx).
• Public endpoints only return series where isActive = true.
• Reorder accepts an array of { id: number, order: number } and updates all rows in a loop (no transaction wrapper; each update is atomic).
• Product-to-series linkage is via product.series_id (nullable FK to brand_series.id).
• Admin list defaults to order ASC, name ASC for consistent storefront ordering.
• Customer list defaults to order ASC, name ASC for consistent display order.
• brandId and categoryId are required for creation; both are validated against existing records.
• description and imageUrl are optional nullable fields.

6. State Models

6.1 Simple active toggle lifecycle

Brand series does not have a complex state machine. The only state dimension is visibility:

isActive = true <--> isActive = false

• isActive = true (default): series appears in customer/public endpoints and can be linked from products.
• isActive = false: series is hidden from customer/public endpoints but remains accessible via admin.
• Product-to-series linkage via product.series_id is independent of the series visibility state.

6.2 No status history table

Unlike Order, Brand Series does not maintain an append-only status history log. State changes are tracked via the updatedAt timestamp only. Audit trails for series visibility changes rely on database-level logging or application-level introspection.

7. Caching Strategy

Read-side keyspaces:

• catalog:brand-series:list:* -- customer list responses
• catalog:brand-series:detail:slug:* -- customer slug-based detail

Configured TTL:

• CATALOG_CACHE_TTL_SECONDS (default 300, falls back to REDIS_CACHE_TTL_SECONDS then 300).

Admin endpoints bypass cache and query the database directly on every request.

7.1 Invalidation triggers

Admin write operations (create, update, delete, reorder) invalidate:

• All cached list keys via catalog:brand-series:list:* pattern invalidation
• Affected detail keys via catalog:brand-series:detail:slug:<slug> key invalidation

Customer/mobile read endpoints use getOrSet pattern: cache hit returns immediately, cache miss fetches from DB and populates the cache.

7.2 Cache key composition

Customer list cache keys are built from the query parameters:

catalog:brand-series:list:brand:<brandId>-cat:<categoryId>-page:<page>-size:<size>

Customer detail cache keys:

catalog:brand-series:detail:slug:<slug>

8. Rate Limiting

This module does not apply rate limiting.

Customer endpoints are public and currently unthrottled. If storefront abuse is observed, rate limiting can be added via the common @Throttle() decorator or a reverse-proxy layer (e.g. Cloudflare, Nginx).

Admin endpoints rely on the global admin rate limiting defaults.

9. Queue/Worker Features

No queues or workers are used in this module.

All operations are synchronous and complete within the request-response lifecycle. Unlike Order, there are no async commands, no background jobs, and no outbox events.

10. Error UX Mapping

11. Integration Flows

11.1 Admin creates series and associates products

An admin creates a brand series and links products to it.

1. Admin calls POST /api/admin/brand-series with { brandId, categoryId, name, description?, imageUrl?, isActive?, order? }.
2. System validates brand and category exist.
3. System generates URL-safe slug from name with suffix resolution on conflict.
4. System creates brand_series row with isActive: true by default.
5. Product team updates products by setting product.series_id to the new series id.
6. Customer visiting the brand storefront now sees the series in the series list.
7. Customer can drill into series to see all published sellable products.

11.2 Customer discovers brand and browses series

A customer explores a brand's product lineup through series groupings.

1. Customer navigates to brand page on the storefront.
2. Storefront calls GET /api/brand-series?brandId=<brandId> to fetch series for this brand.
3. Customer sees visible series cards (name, description, image, product count).
4. Customer clicks a series to drill in.
5. Storefront calls GET /api/brand-series/:slug for series detail.
6. Response includes productCount showing how many products are available.
7. Storefront displays products filtered by series_id belonging to this series.

11.3 Admin reorders series for storefront sequencing

An admin changes the display order of series within a brand.

1. Admin opens brand series management in admin panel.
2. Admin uses drag-and-drop to reorder series items.
3. Admin panel calls PUT /api/admin/brand-series/reorder with { items: [{ id: 1, order: 0 }, { id: 2, order: 1 }] }.
4. System updates each series order field individually.
5. Admin list cache is invalidated via pattern catalog:brand-series:list:*.
6. On next storefront load, series display in the new order.

12. Release/QA Checklist

• Admin list returns all series with correct pagination, brandId/categoryId/isActive filters.
• Admin create validates brand and category existence; returns BRAND_NOT_FOUND/CATEGORY_NOT_FOUND for invalid references.
• Admin create auto-generates slug; duplicate name within brand-category returns BRAND_SERIES_DUPLICATE.
• Admin update with name change regenerates slug and invalidates old+new detail cache.
• Admin reorder updates all items in the array; list cache is invalidated.
• Admin delete removes series and invalidates list+detail cache.
• Customer list returns only isActive = true series; respects brandId/categoryId filters.
• Customer detail by slug returns 404 for inactive or non-existent series.
• Customer detail includes accurate productCount (published + sellable products only).
• Mobile-composed routes (/api/mobile/brand-series/...) resolve through MobileModule routing.
• Cache TTL is respected; writes invalidate customer list and detail cache correctly.

13. See Also

• API Reference: See Brand Series - API & Integration Guide Section 11 (Endpoint Reference + Payload Cheatsheet) for complete request/response DTOs.
• Backend Reference: See Brand Series - Backend Documentation Section 3 (Data Model) for schema details.
• Brand Module: See /docs/developer/catalog/brand for brand-level feature documentation.
• Product Module: See /docs/developer/product for product-to-series linkage documentation.