@tailor-platform/erp-kit 0.2.0 → 0.2.2

package/src/modules/product-management/docs/commands/UpdateProductCategory.md

@@ -0,0 +1,46 @@
+# UpdateProductCategory
+
+## Overview
+
+updateProductCategory modifies the display name of an existing product category. In extensible module configurations, consumer-defined custom fields may also be updated through this command. Category code and parent reference are immutable through this command — use moveProductCategory to change the parent.
+
+## Business Rules
+
+- Target category must exist
+- Category code is immutable — cannot be changed
+- At least one updatable field must be provided
+- Name must remain non-empty when provided
+- Consumer-defined custom fields may be updated
+- Updating name does not affect product assignments or child categories
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Category exists?}
+    B -->|No| C[Return error: CATEGORY_NOT_FOUND]
+    B -->|Yes| D{Code change attempted?}
+    D -->|Yes| E[Return error: CODE_IMMUTABLE]
+    D -->|No| F{Any updatable fields provided?}
+    F -->|No| G[Return error: MISSING_REQUIRED_FIELD]
+    F -->|Yes| H[Apply name and/or custom field updates]
+    H --> I[Return updated category]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **CATEGORY_NOT_FOUND**: Specified category ID does not exist
+- **CODE_IMMUTABLE**: Attempt to change the category code
+- **MISSING_REQUIRED_FIELD**: No updatable fields were provided, or name is empty when provided without any custom field updates
+
+## Test Cases
+
+- should return CategoryNotFoundError when category does not exist
+- should return CodeImmutableError when code is provided
+- should return MissingRequiredFieldError when no fields are provided
+- should pass custom fields through to update
+- should update category name successfully

package/src/modules/product-management/docs/features/attribute-management.md

@@ -0,0 +1,48 @@
+# Attribute Management
+
+## Overview
+
+Attributes define the variant axes of products. Each attribute is identified by a unique code and has a display name. Attributes hold a set of predefined values (e.g., "Red", "Blue" for a Color attribute). Products generate variants from the cartesian product of their assigned attribute values.
+
+## Business Purpose
+
+A flexible attribute system is essential for variant generation:
+
+- **Variant axes** (e.g., Color, Size) determine the combinations that generate product variants. Each axis value maps to a distinct variant
+- Attributes are always variant axes — there are no "descriptive-only" attributes in this module. Descriptive product information is handled via product fields or other modules
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Attribute] --> B[Add Attribute Values]
+    B --> C[Assign to Product]
+    C --> D[Generate Variants]
+```
+
+## Scenario Patterns
+
+- **Color Attribute**: A "Color" attribute is created with values Red, Blue, Green. When assigned to a product, these values drive variant generation
+- **Size Attribute**: A "Size" attribute is created with values S, M, L. Combined with Color, it produces the cartesian product (e.g., Red/S, Red/M, ..., Green/L)
+- **Numeric Values as Select**: Values like "10mm", "12mm", "14mm" are modeled as select values, not as numeric types — they are discrete options for variant generation
+- **Attribute Value Addition**: New values (e.g., "Yellow") are added to an existing attribute. Products using this attribute can then include the new value in variant generation
+- **Attribute Name Update**: An attribute's display name can be updated at any time (e.g., renaming "Colour" to "Color"). The attribute's code remains unchanged
+- **Attribute Value Label Update**: A value's display label can be updated at any time (e.g., fixing a typo, changing language). The value's identity (ID) is preserved, so existing variant references and generated SKUs are unaffected
+- **Axis Structure Locked**: Once a product is ACTIVE, the set of attributes assigned to it is locked. New attributes cannot be assigned — only new values can be added to existing attributes. This prevents structure changes that would invalidate existing variants
+- **Attribute Value Removal**: A value is removed from an attribute only if no ACTIVE product uses it as a variant value
+- **Attribute Deletion**: An attribute can only be deleted if it is not assigned to any product
+
+## Test Cases
+
+- Attributes require a unique code and a display name
+- Attribute code is immutable after creation
+- Attribute value labels can be updated at any time without affecting variant structure or SKUs
+- Attributes must have at least one value before being used for variant generation
+- Attribute values must be unique within the attribute
+- Attribute deletion is blocked if the attribute is assigned to any product
+- Attribute value removal is blocked if the value is in use on any ACTIVE product
+
+## Reference Links
+
+- [Odoo Product Attributes](https://www.odoo.com/documentation/19.0/applications/sales/sales/products_prices/products/variants.html)
+- [Akeneo Attribute Types](https://help.akeneo.com/pim/serenity/articles/what-about-products-variants.html)

package/src/modules/product-management/docs/features/product-category.md

@@ -0,0 +1,71 @@
+# Product Category
+
+## Overview
+
+Product categories provide a hierarchical tree structure for classifying products. Each category is identified by a unique code and has a display name. Categories organize the commercial/marketing view of products (e.g., Apparel > Men's > T-Shirts). Products can belong to multiple categories (many-to-many), enabling multi-dimensional classification. This is distinct from item-management's taxonomy, which classifies Items at the SKU level.
+
+## Business Purpose
+
+Product categories serve the commercial organization of product lines:
+
+- Marketing teams organize products into browsable hierarchies for catalogs, e-commerce navigation, and reporting
+- Multiple category trees can coexist (e.g., one by product type, another by season or collection)
+- Categories at the product level group related products (and their variants) together, while item-management's taxonomy classifies individual SKUs for operational purposes
+
+The separation from item taxonomy ensures:
+
+- Product teams can reorganize commercial categories without affecting operational item classification
+- A product (e.g., "Classic T-Shirt") belongs to a marketing category, while its individual Items (SKUs) may have separate taxonomy assignments for warehouse or procurement purposes
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Root Category] --> B[Create Child Categories]
+    B --> C[Build category tree]
+    C --> D[Assign products to categories]
+    D --> E{Product in multiple categories?}
+    E -->|Yes| F[Create additional assignments]
+    E -->|No| G[Single assignment]
+```
+
+Example category tree structure:
+
+```mermaid
+flowchart TD
+    R[Root: All Products] --> A[Apparel]
+    R --> B[Accessories]
+    A --> C[Men's]
+    A --> D[Women's]
+    C --> E[T-Shirts]
+    C --> F[Pants]
+    D --> G[Dresses]
+    B --> H[Bags]
+    B --> I[Jewelry]
+```
+
+## Scenario Patterns
+
+- **Category Tree Setup**: A root category "All Products" is created, then child categories are added hierarchically (Apparel > Men's > T-Shirts)
+- **Multi-Category Assignment**: A "Unisex T-Shirt" product is assigned to both "Men's > T-Shirts" and "Women's > T-Shirts" categories
+- **Category Reorganization**: A category is moved from one parent to another (e.g., "Accessories" moved under "Apparel")
+- **Category Deletion**: A leaf category with no product assignments is deleted. Categories with assignments or children cannot be deleted
+- **Depth Limit**: Category tree depth is configurable (default max depth enforced to prevent excessively deep hierarchies)
+
+## Test Cases
+
+- Categories require a unique code (globally unique) and a display name
+- Category code is immutable after creation
+- Root categories have no parent
+- Child categories reference a valid parent category
+- Category tree respects a configurable maximum depth
+- Circular references are prevented (a category cannot be its own ancestor)
+- Products can be assigned to multiple categories (many-to-many)
+- Category deletion is blocked if the category has child categories or product assignments
+- Moving a category updates all descendant paths
+- Category names can be updated without affecting product assignments
+
+## Reference Links
+
+- [Odoo Product Categories](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/product_management.html)
+- [Akeneo Category Trees](https://help.akeneo.com/pim/serenity/articles/what-about-products-variants.html)

package/src/modules/product-management/docs/features/product-lifecycle.md

@@ -0,0 +1,66 @@
+# Product Lifecycle
+
+## Overview
+
+Products are the central entity in the Product Management module. A product represents a commercial product — identified by a unique code, along with its name, description, and attribute assignments. Products serve as the parent entity from which variants are generated. Each product has a lifecycle state machine (DRAFT → ACTIVE ↔ ARCHIVED) that controls when variant generation and downstream operations are permitted.
+
+## Business Purpose
+
+Products provide the commercial/marketing view of a product, separate from the operational SKU-level Item in item-management. This separation enables:
+
+- Marketing and product teams to define product structure and descriptions before SKUs exist
+- Attribute assignment and configuration before generating actual Items
+- Archival of discontinued product lines while preserving generated Items for historical transactions
+  The lifecycle ensures:
+
+- Products are reviewed before variant generation is allowed (DRAFT → ACTIVE)
+- Archived products stop generating new variants but existing Items remain unaffected
+- Only DRAFT products can be permanently deleted; ACTIVE/ARCHIVED products are preserved
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createProduct
+    Draft --> Active: activateProduct
+    Active --> Archived: deactivateProduct
+    Archived --> Active: reactivateProduct
+    Draft --> [*]: deleteProduct
+```
+
+The product creation and setup flow follows this pattern:
+
+```mermaid
+flowchart TD
+    A[Create Product] --> B[Assign Attributes]
+    B --> C{Ready for variants?}
+    C -->|Yes| D[Activate Product]
+    C -->|No| E[Continue editing]
+    E --> B
+    D --> F[Generate Variants]
+```
+
+## Scenario Patterns
+
+- **New Product Setup**: A product is created in DRAFT, attributes are assigned (Color, Size), then the product is activated
+- **Product Line Archival**: An entire product line is archived. The product moves to ARCHIVED status, preventing new variant generation, but all existing Items remain ACTIVE in item-management
+- **Product Relaunch**: A previously archived product is reactivated for a new season, allowing new variant generation with updated attribute values
+- **Draft Cleanup**: Unfinished products in DRAFT are deleted before activation
+- **Product Update**: An ACTIVE product's name and description can be updated. New attribute values can be added to existing attributes (to support incremental variant generation), but existing values cannot be modified or removed to preserve variant consistency
+
+## Test Cases
+
+- Product lifecycle follows DRAFT → ACTIVE ↔ ARCHIVED state machine
+- Products can only be created in DRAFT status
+- Only DRAFT products can be deleted; ACTIVE and ARCHIVED products cannot
+- Product code is required, unique, and immutable after creation
+- Product name is required and must be non-empty
+- On ACTIVE products, new attribute values can be added but existing values cannot be modified or removed
+- On DRAFT products, all attribute operations (add, modify, remove) are allowed
+- Archiving a product does not affect existing Items generated from its variants
+- Reactivating an ARCHIVED product returns it to ACTIVE status
+
+## Reference Links
+
+- [Odoo Product Variants](https://www.odoo.com/documentation/19.0/applications/sales/sales/products_prices/products/variants.html)
+- [Akeneo Product Model](https://help.akeneo.com/pim/serenity/articles/what-about-products-variants.html)

package/src/modules/product-management/docs/features/variant-generation.md

@@ -0,0 +1,77 @@
+# Variant Generation
+
+## Overview
+
+Variant generation creates product variants from the combination of attribute values on an ACTIVE product. Each variant represents a unique attribute combination (e.g., Red/S, Red/M, Blue/S, Blue/M). Upon generation, each variant creates a corresponding Item in the item-management module with a SKU produced by an injectable SKU generation strategy, inheriting the product's UoM configuration.
+
+## Business Purpose
+
+Variant generation is the bridge between the commercial product view (product-management) and the operational SKU view (item-management):
+
+- Product teams define the product structure (product + attributes) in product-management
+- Variant generation materializes this structure into concrete, tradeable Items
+- Each Item receives a unique SKU produced by the injectable SKU generation strategy (default: sequential numbering based on product code, e.g., `CLASSIC-TSHIRT-001`)
+- Generated Items can then participate in inventory, sales, and purchasing workflows independently
+
+This separation ensures:
+
+- Product structure changes (adding a new color) can be planned before creating SKUs
+- Only ACTIVE products can generate variants, preventing premature Item creation
+- The relationship between a product and its generated Items is tracked for traceability
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Product - ACTIVE] --> B[Collect attribute assignments]
+    B --> C[Compute attribute value combinations]
+    C --> D{For each combination}
+    D --> E[Check if variant already exists]
+    E -->|Exists| F[Skip]
+    E -->|New| G[Create ProductVariant record]
+    G --> H[Call item-management createItem]
+    H --> I[Link Item to ProductVariant]
+    I --> D
+    D -->|All done| J[Generation complete]
+```
+
+SKU generation logic is **injectable**. Consumers can provide a custom SKU generation strategy when configuring the module; a sensible default is shipped out of the box. The generator receives the product code, axis values, and the current variant count as input and returns a SKU string. The default strategy produces sequential numbering based on the product code, avoiding coupling to attribute value labels:
+
+```mermaid
+flowchart LR
+    A["Product code: 'CLASSIC-TSHIRT'"] --> B["Variant count: 0"]
+    B --> C["SKU: CLASSIC-TSHIRT-001"]
+```
+
+Custom strategy examples include attribute-value slug (`CLASSIC-TSHIRT-RED-M`), prefix by brand (`ACME-CTSHIRT-001`), or hash-based (`CT-a3f8b2`).
+
+## Scenario Patterns
+
+- **Full Generation**: A product with Color (Red, Blue) × Size (S, M, L) generates 6 variants. Each variant creates an Item in item-management with a SKU produced by the configured SKU generation strategy (default: `CLASSIC-TSHIRT-001` through `CLASSIC-TSHIRT-006`)
+- **Incremental Generation**: A new color (Green) is added to a product. Re-running generation creates only the 3 new variants (Green/S, Green/M, Green/L), skipping existing ones
+- **Single Axis**: A product with only one attribute (e.g., Size: S, M, L) generates 3 variants
+- **Generation Blocked**: Attempting to generate variants from a DRAFT or ARCHIVED product is rejected
+- **Axis Structure Locked**: Once a product is ACTIVE, the set of assigned attributes is locked. New attributes cannot be assigned; only new values can be added to existing attributes
+- **Generated Item Independence**: After generation, the Item's lifecycle is independent — deactivating an Item in item-management does not affect the product or other variants
+- **Variant Traceability**: Each ProductVariant record links the product, the specific axis values, and the generated Item ID for full traceability
+
+## Test Cases
+
+- Variants can only be generated from ACTIVE products
+- Each variant represents a unique combination of attribute values
+- Duplicate combinations are skipped during generation (idempotent)
+- Each generated variant creates exactly one Item in item-management
+- Generated Item SKU is produced by the injectable SKU generation strategy (defaults to sequential numbering based on product code)
+- A custom SKU generation strategy can be provided at module configuration time
+- The strategy receives product code, axis values, and current variant count, and must return a unique string
+- The default strategy avoids coupling SKUs to attribute value labels, ensuring label updates do not create inconsistencies
+- Generated Item inherits the product's configured UoM
+- Generated Items are created in DRAFT status (requiring explicit activation in item-management)
+- ProductVariant records store the product ID, axis value combination, and generated Item ID
+- Variant generation fails atomically if any Item creation fails (no partial generation)
+- The set of assigned attributes is locked on non-DRAFT products — new attributes cannot be assigned after activation
+
+## Reference Links
+
+- [Odoo Variant Creation Modes](https://www.odoo.com/documentation/19.0/applications/sales/sales/products_prices/products/variants.html)
+- [Akeneo Family Variant Levels](https://help.akeneo.com/pim/serenity/articles/what-about-products-variants.html)

package/src/modules/product-management/docs/models/Product.md

@@ -0,0 +1,58 @@
+# Product
+
+## Description
+
+Product is the central entity in the Product Management module. A product represents a commercial product -- identified by a unique code, along with its name, description, and unit of measure. Products serve as the parent entity from which variants are generated via attribute combinations. Each product has a lifecycle state machine (DRAFT -> ACTIVE <-> ARCHIVED) that controls when variant generation and downstream operations are permitted.
+
+Products provide the commercial/marketing view of a product, separate from the operational SKU-level Item in item-management. Only ACTIVE products can generate variants. Only DRAFT products can be permanently deleted.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createProduct
+    Draft --> Active: activateProduct
+    Active --> Archived: deactivateProduct
+    Archived --> Active: reactivateProduct
+    Draft --> [*]: deleteProduct
+```
+
+### Command Definitions
+
+- [createProduct](../commands/CreateProduct.md) - Create a new product in DRAFT status
+- [updateProduct](../commands/UpdateProduct.md) - Update mutable fields of an existing product
+- [activateProduct](../commands/ActivateProduct.md) - Transition product from DRAFT to ACTIVE
+- [deactivateProduct](../commands/DeactivateProduct.md) - Transition product from ACTIVE to ARCHIVED
+- [reactivateProduct](../commands/ReactivateProduct.md) - Transition product from ARCHIVED to ACTIVE
+- [deleteProduct](../commands/DeleteProduct.md) - Permanently delete a DRAFT product
+
+### Query Definitions
+
+- GetProduct - Retrieve a product by id or code
+
+### Models
+
+- Product
+
+### Invariants
+
+- Product code is required, globally unique, and immutable after creation
+- Product name is required and must be non-empty
+- Products are always created in DRAFT status
+- Only DRAFT products can be deleted; ACTIVE and ARCHIVED products are preserved
+- Assigned attributes are freely modifiable in DRAFT status; on ACTIVE products only additive changes are allowed (new values for existing attributes); on ARCHIVED products all attribute changes are blocked
+- Archiving a product does not affect existing Items generated from its variants
+- UoM must reference an existing active Unit from the primitives module
+
+### Relationships
+
+- **References Unit**: Each product references a Unit from the primitives module as its unit of measure
+- **Has Many ProductAttributeAssignments**: Product attribute assignments link attributes and their values to this product
+- **Has Many ProductVariants**: Variants are generated from this product's attribute combinations
+- **Has Many ProductCategoryAssignments**: Products are linked to ProductCategories via many-to-many assignments

package/src/modules/product-management/docs/models/ProductAttribute.md

@@ -0,0 +1,37 @@
+# ProductAttribute
+
+## Description
+
+ProductAttribute defines a variant axis that can be assigned to products. Each attribute is identified by a unique code and has a display name. Attributes hold predefined values (e.g., "Red", "Blue", "Green" for a Color attribute) that drive variant generation. All attributes are variant axes — there are no descriptive-only attributes in this module.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createProductAttribute](../commands/CreateProductAttribute.md) - Create a new attribute
+- [updateProductAttribute](../commands/UpdateProductAttribute.md) - Update the display name of an existing attribute
+- [deleteProductAttribute](../commands/DeleteProductAttribute.md) - Delete an attribute that is not assigned to any product
+
+### Query Definitions
+
+- GetProductAttribute - Retrieve an attribute by id or code
+
+### Models
+
+- ProductAttribute
+
+### Invariants
+
+- Attribute code is required, globally unique, and immutable after creation
+- Attribute name is required and must be non-empty
+- Attributes must have at least one ProductAttributeValue before being used for variant generation
+- Attribute deletion is blocked if the attribute is assigned to any product
+
+### Relationships
+
+- **Has Many ProductAttributeValues**: Attributes have a set of predefined values
+- **Referenced By ProductAttributeAssignments**: Attributes are assigned to products via attribute assignment records

package/src/modules/product-management/docs/models/ProductAttributeAssignment.md

@@ -0,0 +1,41 @@
+# ProductAttributeAssignment
+
+## Description
+
+ProductAttributeAssignment records the assignment of a single attribute value to a specific product. A product can have multiple assignments for the same attribute, each carrying a different value (e.g., Color=Red, Color=Blue, Color=Green). All assignments participate in variant generation — the set of values per attribute defines the variant axes.
+
+This model is the junction between Product and ProductAttribute, carrying the actual attribute values for each product.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [setProductAttributeAssignment](../commands/SetProductAttributeAssignment.md) - Set or update an attribute value on a product
+
+### Query Definitions
+
+- GetProductAttributeAssignment - Retrieve a specific assignment by productId and attributeId
+- ListProductAttributeAssignments - Retrieve all attribute assignments for a given product
+
+### Models
+
+- ProductAttributeAssignment
+
+### Invariants
+
+- Each record references a valid Product and a valid ProductAttribute
+- The combination of (productId, attributeId, valueId) must be unique — multiple values per attribute are allowed
+- The value must reference a valid ProductAttributeValue belonging to the attribute
+- On DRAFT products: assignments can be freely created and removed
+- On ACTIVE products: adding new values to an already-assigned attribute is allowed (additive-only); removing existing values or assigning a new attribute is blocked
+- On ARCHIVED products: all assignment changes are blocked
+
+### Relationships
+
+- **Belongs To Product**: Each record is associated with exactly one product
+- **Belongs To ProductAttribute**: Each record references exactly one attribute definition
+- **References ProductAttributeValue**: The value references a predefined option

package/src/modules/product-management/docs/models/ProductAttributeValue.md

@@ -0,0 +1,40 @@
+# ProductAttributeValue
+
+## Description
+
+ProductAttributeValue represents a predefined option for a ProductAttribute. Each value belongs to exactly one attribute and has a unique label within that attribute. Values define the available options for attributes (e.g., "Red", "Blue", "Green" for a Color attribute) and serve as the axis values for variant generation.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createProductAttributeValue](../commands/CreateProductAttributeValue.md) - Create a new value for an attribute
+- [updateProductAttributeValue](../commands/UpdateProductAttributeValue.md) - Update the display label of an existing value
+- [deleteProductAttributeValue](../commands/DeleteProductAttributeValue.md) - Delete a value from an attribute
+
+### Query Definitions
+
+- GetProductAttributeValue - Retrieve a single value by id or by attributeId + label
+- ListProductAttributeValues - Retrieve all values for a given attribute
+
+### Models
+
+- ProductAttributeValue
+
+### Invariants
+
+- Each value must belong to exactly one ProductAttribute
+- Value label must be unique within the parent attribute
+- Value label can be updated at any time (display-only change; identity is preserved)
+- Value removal is blocked if the value is in use on any ACTIVE product
+- Adding values is always allowed for any attribute
+
+### Relationships
+
+- **Belongs To ProductAttribute**: Each value belongs to exactly one attribute
+- **Referenced By ProductAttributeAssignments**: Values are referenced when assigning attribute values to products
+- **Referenced By ProductVariants**: Variant axis values reference these records for traceability

package/src/modules/product-management/docs/models/ProductCategory.md

@@ -0,0 +1,46 @@
+# ProductCategory
+
+## Description
+
+ProductCategory represents a single node in a hierarchical tree structure used to classify products for commercial and marketing purposes. Each category is identified by a globally unique code and has a display name. Root categories have no parent. Categories can be reorganized by moving them to a different parent, and children follow their parent.
+
+This is distinct from item-management's taxonomy, which classifies Items at the SKU level. Product categories organize the commercial view of products (e.g., Apparel > Men's > T-Shirts).
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createProductCategory](../commands/CreateProductCategory.md) - Create a new root or child category
+- [updateProductCategory](../commands/UpdateProductCategory.md) - Update the display name of an existing category
+- [moveProductCategory](../commands/MoveProductCategory.md) - Reparent a category within the tree
+- [deleteProductCategory](../commands/DeleteProductCategory.md) - Delete a leaf category with no product assignments
+
+### Query Definitions
+
+- GetProductCategory - Retrieve a category by id or code
+- ListProductCategoryChildren - Retrieve direct child categories of a given category
+
+### Models
+
+- ProductCategory
+
+### Invariants
+
+- Category code is required, globally unique, and immutable after creation
+- Category name is required and must be non-empty
+- Root categories have a null parent reference
+- Child categories must reference a valid existing parent category
+- Category tree respects a configurable maximum depth (prevents excessively deep hierarchies)
+- Circular references are prevented -- a category cannot be its own ancestor
+- Category deletion is blocked if the category has child categories
+- Category deletion is blocked if the category has product assignments
+- Moving a category updates the category's parent reference while preserving its descendants
+
+### Relationships
+
+- **Self-Referential Parent-Child**: Each category optionally references another ProductCategory as its parent, forming a tree
+- **Referenced By ProductCategoryAssignments**: Categories are linked to products via many-to-many assignments

package/src/modules/product-management/docs/models/ProductCategoryAssignment.md

@@ -0,0 +1,37 @@
+# ProductCategoryAssignment
+
+## Description
+
+ProductCategoryAssignment is the junction entity that links products to product categories in a many-to-many relationship. A product can belong to multiple categories (e.g., a "Unisex T-Shirt" in both "Men's > T-Shirts" and "Women's > T-Shirts"), and a category can contain multiple products.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [assignProductToCategory](../commands/AssignProductToCategory.md) - Assign a product to a category
+- [removeProductFromCategory](../commands/RemoveProductFromCategory.md) - Remove a product from a category
+
+### Query Definitions
+
+- GetProductCategoryAssignment - Retrieve a specific assignment by productId and categoryId
+- ListProductCategoryAssignments - Retrieve all product assignments for a given category
+- ListCategoryAssignmentsByProduct - Retrieve all category assignments for a given product
+
+### Models
+
+- ProductCategoryAssignment
+
+### Invariants
+
+- Each assignment references a valid Product and a valid ProductCategory
+- The combination of (productId, categoryId) must be unique (no duplicate assignments)
+- Assignment is idempotent -- assigning an already-assigned product returns the existing record
+
+### Relationships
+
+- **Belongs To Product**: Each assignment links to exactly one product
+- **Belongs To ProductCategory**: Each assignment links to exactly one category

package/src/modules/product-management/docs/models/ProductVariant.md

@@ -0,0 +1,41 @@
+# ProductVariant
+
+## Description
+
+ProductVariant represents a unique combination of attribute values generated from an ACTIVE product. Each variant links the product, the specific value combination, and the generated Item ID in item-management. Variants are created during the variant generation process and provide full traceability between the commercial product structure and operational SKUs.
+
+Variant generation is idempotent -- existing combinations are skipped, and only new combinations create new variant records and corresponding Items.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [generateVariants](../commands/GenerateVariants.md) - Generate variants from attribute value combinations on an ACTIVE product
+
+### Query Definitions
+
+- GetProductVariant - Retrieve a single variant by id or by productId + axisValueKey
+- ListProductVariants - Retrieve all variants for a given product
+
+### Models
+
+- ProductVariant
+
+### Invariants
+
+- Each variant represents a unique combination of attribute values within a product
+- Each variant is associated with exactly one generated Item in item-management
+- The value combination (`productId` + `axisValueKey`) must be unique
+- `axisValueKey` is a canonical string key derived from sorted value IDs (e.g., `"value-1|value-3"`)
+- Variants can only be created from ACTIVE products
+- Once created, variant records are immutable (the link between product, values, and Item is permanent)
+
+### Relationships
+
+- **Belongs To Product**: Each variant is generated from exactly one product (`productId`)
+- **References ProductAttributeValues**: Each variant stores the specific value combination via `axisValueKey`
+- **References item-management::Item**: Each variant links to the Item created during generation (`itemId`)