Product Catalog — Design Document

Full-featured business module with CRUD, variants (master-detail), workflow, media, cross-module integration, and embeddable widgets.

Architecture

Product Catalog is a complete business module — it owns its entities (Product, ProductVariant), has full CRUD pages, workflow-based status transitions, media integration, and exposes public actions and embeddable components for other modules.

product-catalog (Business Module)
├── Owns: Product, ProductVariant, ProductAttribute
├── Consumes: @libs-core/fiscal         → TaxClass selector in product form
├── Consumes: @libs-core/brand-registry → Brand selector in product form
├── Consumes: @libs-core/taxonomy       → Category selector, Tag input in product form
├── Consumes: @libs-core/workflow-engine → Status transitions (draft → active → discontinued)
├── Consumes: @libs-core/media          → Product image upload and gallery
├── Consumes: @libs-core/module-base    → CRUD composables, module contract, master-detail
├── Consumes: @libs-core/ui-framework   → Shell components, form controls
├── Consumes: @libs-core/event-system   → Domain event publishing/subscribing
├── Consumes: @libs-core/action-registry → Public action registration
└── Consumes: @libs-core/security       → Guards, context service

Data Models

Product (Primary Entity)

interface Product extends BaseEntity {
  tenantId: string;
  name: string;
  slug: string;
  sku: string;
  barcode?: string;
  description?: string;
  shortDescription?: string;
  type: ProductType;         // 'physical' | 'digital' | 'service'
  status: ProductStatus;     // 'draft' | 'active' | 'discontinued'
  categoryId: string;        // FK → Category (taxonomy)
  brandId?: string;          // FK → Brand (brand-registry)
  tags: string[];            // Tag IDs (taxonomy)
  unit?: UnitOfMeasure;      // 'unit' | 'kg' | 'g' | 'lb' | 'oz' | 'l' | 'ml' | ...
  taxClassId?: string;       // FK → TaxClass (fiscal)
  hasVariants: boolean;
  basePrice: number;
  costPrice?: number;
  compareAtPrice?: number;
  currency?: string;
  weight?: number;
  weightUnit?: string;
  dimensions?: ProductDimensions;  // { length, width, height, unit }
  isOnlineAvailable?: boolean;
  isFeatured?: boolean;
  sortOrder?: number;
  seo?: ProductSeo;          // { metaTitle, metaDescription, metaKeywords }
  notes?: string;
  imageUrl?: string;
  createdAt: string;
  updatedAt: string;
}

ProductVariant (Child Entity — 1:N with Product)

interface ProductVariant extends BaseEntity {
  productId: string;         // FK → Product
  sku: string;
  barcode?: string;
  attributeValues: Record<string, string>;  // e.g., { "Size": "M", "Color": "Red" }
  price: number;
  costPrice?: number;
  compareAtPrice?: number;
  weight?: number;
  isActive: boolean;
  sortOrder: number;
  imageId: string | null;
  createdAt: string;
  updatedAt: string;
}

ProductAttribute (Supporting Entity)

interface ProductAttribute {
  id: string;
  productId: string;
  name: string;              // e.g., "Size", "Color"
  values: string[];          // e.g., ["S", "M", "L", "XL"]
  sortOrder: number;
}

Permissions

Workflow: Product Status

         publish              discontinue
  ┌───────┐ ────────► ┌──────┐ ────────► ┌──────────────┐
  │ draft │            │active│            │ discontinued │
  └───────┘            └──────┘ ◄──────── └──────────────┘
                                reactivate

Definition: PRODUCT_STATUS_WORKFLOW

Integration: Uses <lib-status-transition> component in ProductDetailComponent. On transition completed, calls ProductApiService.updateProductStatus() and refreshes entity + workflow history.

Navigation: Hierarchical

navigation: {
  menuItems: [
    {
      id: 'catalog-parent',
      label: 'Catalog',
      icon: 'box-open',
      order: 300,
      permissions: ['catalog:read'],
      children: [
        { id: 'catalog-products', label: 'All Products', icon: 'list', route: 'list', order: 10, permissions: ['catalog:read'] },
        { id: 'catalog-new', label: 'New Product', icon: 'plus', route: 'create', order: 20, permissions: ['catalog:create'] },
      ],
    },
  ],
},

Routes

All routes guarded with: authGuard → contextGuard → permissionGuard(permission).

Workflow provider registered at route level:

{ path: '', providers: [provideProductWorkflow()], children: [...] }

Components

ProductListComponent

• Uses useCrudList<Product> with ProductApiService
• Filters: type (select: physical/digital/service), status (select: draft/active/discontinued), search (text)
• Columns: name, sku, type, status (badge), basePrice (formatted), brand
• View modes: table (default), cards, compact
• Pagination: configurable page size

ProductDetailComponent

• Uses useCrudDetail<Product> with ProductApiService
• Sections:
  • Header: product name, SKU, status badge
  • Status transition: <lib-status-transition entityType="product" [entity]="product()">
  • Info cards: pricing, dimensions, SEO
  • Media gallery: <lib-entity-media-section entityType="product-photo" [entityId]="product().id">
  • Variants table: <lib-variant-list [productId]="product().id">
  • Workflow history: status transition timeline

ProductFormComponent

• Uses useCrudForm<Product> with ProductApiService
• Sections:
  • Basic info: name, slug, SKU, barcode, description
  • Classification: <lib-category-selector>, <lib-brand-selector>, <lib-tag-input>
  • Pricing: basePrice, costPrice, compareAtPrice, currency, <lib-tax-class-selector>
  • Physical properties: weight, dimensions, unit of measure
  • Options: type, isOnlineAvailable, isFeatured
  • SEO: metaTitle, metaDescription, metaKeywords
  • Media: <lib-entity-media-section> (edit mode only)

VariantListComponent

• Embedded in ProductDetailComponent
• Uses ProductVariantApiService
• Displays variant table with: SKU, attribute values, price, status
• Inline add/edit/delete actions
• Attribute management (define attributes → generate combinations)

VariantFormComponent

• Create/edit form for a single variant
• Dynamic fields based on product's attribute definitions
• Fields: SKU, barcode, price, costPrice, weight, isActive

Master-Detail: Product → Variants

readonly crud = useMasterDetail<Product, ProductVariant>({
  parentApiService: this.productApi,
  childApiService: this.variantApi,
  basePath: '/catalog',
  childBasePath: 'variants',
  childEntityName: 'ProductVariant',
});

The detail page shows:

• Parent product information at the top
• Child variants in a paginated table below
• Actions: add variant, edit variant (inline), delete variant, generate from attributes

Domain Events

Product Events

Variant Events

Public Actions

Embeddable Components

ProductLookupComponent

• Widget ID: catalog:product-lookup
• Purpose: Search and select products (for use in other modules' forms, e.g., order line item selection)
• Inputs: placeholder (string), multiSelect (boolean)
• Output: selectionChanged (Product[])
• Features: debounced search (300ms), min 2 chars, displays name + SKU + price

ProductCardComponent

• Widget ID: catalog:product-card
• Purpose: Display a product card (for dashboards, detail pages)
• Inputs: product (Product), productId (string), showPrice (boolean), showStatus (boolean), compact (boolean)
• Output: productClicked (Product)
• Features: fetches by ID if product not provided, status badge, compact mode

Mock API

Product Endpoints

Variant Endpoints

Attribute Endpoints

Workflow History Endpoints

Seed Data

15 products:

• 8 physical (2 with variants: T-Shirt with Size/Color, Sneakers with Size)
• 4 digital (e-books, software licenses)
• 3 service (consulting, training sessions)
• Distribution: 10 active, 3 draft, 2 discontinued

Services

ProductApiService

Extends BaseCrudApiService<Product>:

• baseUrl: /api/products
• Additional methods: searchProducts(term, limit), updateProductStatus(id, status)

ProductVariantApiService

Standalone service (does not extend BaseCrudApiService — nested resource):

• getVariantsByProduct(productId) → GET /api/products/:productId/variants
• createVariant(productId, data) → POST /api/products/:productId/variants
• updateVariant(productId, variantId, data) → PUT /api/products/:productId/variants/:variantId
• deleteVariant(productId, variantId) → DELETE /api/products/:productId/variants/:variantId
• getAttributes(productId) → GET /api/products/:productId/attributes
• saveAttributes(productId, attributes) → PUT /api/products/:productId/attributes
• generateVariants(productId) → POST /api/products/:productId/variants/generate

VariantGeneratorService

Pure utility service:

• generateCombinations(attributes: ProductAttribute[]) → cartesian product of attribute values

Building Block Integrations

Module Registration

@ModuleDecorator({
  id: 'product-catalog',
  version: '1.0.0',
  name: 'Product Catalog',
  description: 'Product catalog with CRUD, variants, workflow, and media',
  basePath: 'catalog',
  repositories: [ProductRepository, ProductVariantRepository],
  relations: [
    {
      type: 'one-to-many',
      sourceEntity: 'product',
      targetEntity: 'product-variant',
      foreignKey: 'productId',
      displayField: 'sku',
    },
  ],
  permissions: [/* 7 permissions as listed above */],
  navigation: {/* hierarchical as shown above */},
  tags: ['product-catalog', 'crud', 'workflow', 'media', 'master-detail'],
})

Manifest includes:

• 4 public actions
• 2 embeddable components
• 7 domain events (product + variant lifecycle)