@tailor-platform/erp-kit 0.1.1 → 0.2.0

package/src/modules/item-management/docs/commands/CreateTaxonomyNode.md

@@ -0,0 +1,44 @@
+# CreateTaxonomyNode
+
+## Overview
+
+createTaxonomyNode establishes a new node in the taxonomy hierarchy. A node can be a root node (no parent) or a child node positioned under an existing parent. Each node has a globally unique code for stable API references and integrations, and a display name.
+
+This command supports both initial taxonomy setup and incremental expansion of the classification tree.
+
+## Business Rules
+
+- Node code is required and must be globally unique across all taxonomy nodes
+- Node name is required
+- Parent node ID is optional — omitting it creates a root node
+- When parent is specified, the parent node must exist
+- Creating a child node must not cause the tree to exceed the configurable maximum depth (default 10)
+- Root nodes have a null parent reference
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive create request] --> B{Validate code format}
+    B -->|Invalid| C[Return error: invalid code]
+    B -->|Valid| D{Code unique?}
+    D -->|No| E[Return error: duplicate code]
+    D -->|Yes| F{Parent specified?}
+    F -->|Yes| G{Parent exists?}
+    G -->|No| H[Return error: parent not found]
+    G -->|Yes| I{Depth limit exceeded?}
+    I -->|Yes| J[Return error: max depth exceeded]
+    I -->|No| K[Create node with parent]
+    F -->|No| K[Create root node]
+    K --> L[Return created node]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **DUPLICATE_NODE_CODE**: A node with the same code already exists
+- **PARENT_NODE_NOT_FOUND**: Specified parent node ID does not exist
+- **MAX_DEPTH_EXCEEDED**: Adding this child would exceed the configurable tree depth limit

package/src/modules/item-management/docs/commands/DeactivateItem.md

@@ -0,0 +1,34 @@
+# DeactivateItem
+
+## Overview
+
+deactivateItem transitions an item from ACTIVE to INACTIVE status, removing it from availability for new transactions while preserving it for historical reference and audit trails. This supports scenarios such as discontinuing a product line or seasonal item removal.
+
+## Business Rules
+
+- Target item must exist in the system
+- Target item must be in ACTIVE status
+- Deactivated items remain in the system for reporting and audit purposes
+- Deactivation prevents the item from being used in new transactions
+- Existing transactions referencing this item are not affected
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive deactivate request] --> B{Item exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is ACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to INACTIVE]
+    F --> G[Return deactivated item]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **INVALID_STATE_TRANSITION**: Item is not in ACTIVE status

package/src/modules/item-management/docs/commands/DeleteItem.md

@@ -0,0 +1,35 @@
+# DeleteItem
+
+## Overview
+
+deleteItem permanently removes a DRAFT item from the system. Only items in DRAFT status can be deleted — ACTIVE and INACTIVE items are preserved for audit trails and historical reference. This supports draft cleanup workflows where unwanted items are removed before activation.
+
+## Business Rules
+
+- Target item must exist in the system
+- Target item must be in DRAFT status
+- ACTIVE and INACTIVE items cannot be deleted — they must be preserved for audit trails
+- Deletion is permanent and cannot be undone
+- Any taxonomy assignments for the item should be removed before or as part of deletion
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Item exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is DRAFT?}
+    D -->|No| E[Return error: cannot delete non-draft item]
+    D -->|Yes| F[Remove taxonomy assignments]
+    F --> G[Delete item record]
+    G --> H[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **DELETE_NON_DRAFT**: Item is in ACTIVE or INACTIVE status — only DRAFT items can be deleted

package/src/modules/item-management/docs/commands/DeleteTaxonomyNode.md

@@ -0,0 +1,39 @@
+# DeleteTaxonomyNode
+
+## Overview
+
+deleteTaxonomyNode permanently removes a taxonomy node from the hierarchy. Deletion is only allowed for leaf nodes (no children) with no item assignments. This ensures the classification tree remains consistent and no item classifications are silently lost.
+
+For node consolidation scenarios, item assignments should first be moved to another node using assignItemToTaxonomy and removeItemFromTaxonomy before deleting the empty node.
+
+## Business Rules
+
+- Target node must exist in the system
+- Node must have no child nodes — a node with children cannot be deleted
+- Node must have no item assignments — a node with assigned items cannot be deleted
+- Deletion is permanent and cannot be undone
+- The node's code becomes available for reuse after deletion
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive delete request] --> B{Node exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Has child nodes?}
+    D -->|Yes| E[Return error: has children]
+    D -->|No| F{Has item assignments?}
+    F -->|Yes| G[Return error: has assignments]
+    F -->|No| H[Delete node record]
+    H --> I[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: Specified node ID does not exist
+- **NODE_HAS_CHILDREN**: Node has one or more child nodes — children must be moved or deleted first
+- **NODE_HAS_ASSIGNMENTS**: Node has one or more item assignments — assignments must be removed first

package/src/modules/item-management/docs/commands/MoveTaxonomyNode.md

@@ -0,0 +1,45 @@
+# MoveTaxonomyNode
+
+## Overview
+
+moveTaxonomyNode reparents a taxonomy node by changing its parent reference. The node and all its descendants move together, preserving the subtree structure and all item assignments. This supports taxonomy restructuring scenarios such as promoting a branch to root level or reorganizing classification hierarchies.
+
+Moving to a null parent promotes the node to a root node.
+
+## Business Rules
+
+- Target node must exist in the system
+- New parent node must exist when specified (null for root promotion)
+- A node cannot be moved under itself or any of its descendants (circular reference prevention)
+- All child nodes and their item assignments are preserved during the move
+- The move must not cause the tree to exceed the configurable maximum depth
+- Node code and item assignments are unchanged by the move
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive move request] --> B{Node exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{New parent specified?}
+    D -->|Yes| E{New parent exists?}
+    E -->|No| F[Return error: parent not found]
+    E -->|Yes| G{New parent is descendant of node?}
+    G -->|Yes| H[Return error: circular reference]
+    G -->|No| I{Depth limit exceeded?}
+    I -->|Yes| J[Return error: max depth exceeded]
+    I -->|No| K[Update parent reference]
+    D -->|No/null| K[Promote to root]
+    K --> L[Return moved node]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: Specified node ID does not exist
+- **PARENT_NODE_NOT_FOUND**: Specified new parent node ID does not exist
+- **CIRCULAR_REFERENCE**: New parent is the node itself or one of its descendants
+- **MAX_DEPTH_EXCEEDED**: Moving this subtree would exceed the configurable tree depth limit

package/src/modules/item-management/docs/commands/ReactivateItem.md

@@ -0,0 +1,34 @@
+# ReactivateItem
+
+## Overview
+
+reactivateItem transitions an item from INACTIVE back to ACTIVE status, making a previously discontinued SKU available for transactions again. This supports scenarios such as bringing back seasonal products or restoring items after a temporary suspension.
+
+## Business Rules
+
+- Target item must exist in the system
+- Target item must be in INACTIVE status
+- After reactivation, the item can participate in new transactions
+- All item data (SKU, barcode, UoM, name) is preserved from before deactivation
+- Bulk reactivation is not supported — reactivation is expected to be a targeted, individual operation since bringing back discontinued items requires deliberate per-item review
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive reactivate request] --> B{Item exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Status is INACTIVE?}
+    D -->|No| E[Return error: invalid state transition]
+    D -->|Yes| F[Update status to ACTIVE]
+    F --> G[Return reactivated item]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **INVALID_STATE_TRANSITION**: Item is not in INACTIVE status

package/src/modules/item-management/docs/commands/RemoveItemFromTaxonomy.md

@@ -0,0 +1,30 @@
+# RemoveItemFromTaxonomy
+
+## Overview
+
+removeItemFromTaxonomy deletes the link between an item and a taxonomy node. Removing an assignment does not affect the item itself, the taxonomy node, or any other assignments the item may have. This supports scenarios such as reclassification, node consolidation, and cleanup of incorrect assignments.
+
+## Business Rules
+
+- The assignment (item + taxonomy node link) must exist in the system
+- Removing an assignment does not affect the item or its other taxonomy assignments
+- Removing an assignment does not affect the taxonomy node or its other item assignments
+- Removal is permanent and cannot be undone
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive remove request] --> B{Assignment exists?}
+    B -->|No| C[Return error: assignment not found]
+    B -->|Yes| D[Delete assignment record]
+    D --> E[Return success]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **ASSIGNMENT_NOT_FOUND**: No assignment exists for the specified item and taxonomy node combination

package/src/modules/item-management/docs/commands/UpdateItem.md

@@ -0,0 +1,55 @@
+# UpdateItem
+
+## Overview
+
+updateItem modifies mutable fields of an existing item — name, barcode, and unit of measure (UoM). SKU is immutable and cannot be changed after creation. The set of updatable fields depends on the item's current lifecycle status.
+
+This command supports the DRAFT review workflow (correcting barcodes, setting names before activation) as well as post-activation updates to non-transactional fields.
+
+## Business Rules
+
+- Target item must exist in the system
+- SKU is immutable — any attempt to change SKU returns an error
+- Name can be updated in any status (DRAFT, ACTIVE, INACTIVE)
+- Barcode can be updated in any status; must remain unique across all items when provided
+- Barcode can be cleared (set to null) to remove it from the item
+- UoM can be updated only when the item is in DRAFT status — once activated, UoM is locked to preserve transaction consistency
+- UoM must reference an existing active Unit from the primitives module
+- At least one field must be provided for update (no-op updates are rejected)
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Item exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{SKU change attempted?}
+    D -->|Yes| E[Return error: SKU immutable]
+    D -->|No| F{Any field provided?}
+    F -->|No| G[Return error: no fields to update]
+    F -->|Yes| H{Barcode provided?}
+    H -->|Yes| I{Barcode unique?}
+    I -->|No| J[Return error: duplicate barcode]
+    I -->|Yes| K{UoM change requested?}
+    H -->|No| K
+    K -->|Yes| L{Status is DRAFT?}
+    L -->|No| M[Return error: UoM locked after activation]
+    L -->|Yes| N{UoM valid and active?}
+    N -->|No| O[Return error: invalid UoM]
+    N -->|Yes| P[Apply updates]
+    K -->|No| P
+    P --> Q[Return updated item]
+```
+
+## External Dependencies
+
+- [primitives::Unit](../../../primitives/docs/models/Unit.md) - Validates that the referenced UoM exists and is active (when UoM is being updated)
+
+## Error Scenarios
+
+- **ITEM_NOT_FOUND**: Specified item ID does not exist
+- **SKU_IMMUTABLE**: Attempt to change the SKU field
+- **DUPLICATE_BARCODE**: An item with the same barcode already exists
+- **UNIT_NOT_FOUND**: Referenced unit does not exist or is inactive
+- **UOM_LOCKED**: UoM cannot be changed after item has been activated (status is ACTIVE or INACTIVE)
+- **NO_FIELDS_TO_UPDATE**: No updatable fields were provided in the request

package/src/modules/item-management/docs/commands/UpdateTaxonomyNode.md

@@ -0,0 +1,36 @@
+# UpdateTaxonomyNode
+
+## Overview
+
+updateTaxonomyNode modifies the display name of an existing taxonomy node. The node code is immutable and cannot be changed after creation — only the name (display label) can be updated. This supports scenarios such as renaming a classification branch to better reflect its contents or aligning terminology across the organization.
+
+## Business Rules
+
+- Target node must exist in the system
+- Node code is immutable — any attempt to change the code returns an error
+- Name is required and must not be empty
+- Name update does not affect the node's position in the tree, child nodes, or item assignments
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive update request] --> B{Node exists?}
+    B -->|No| C[Return error: not found]
+    B -->|Yes| D{Code change attempted?}
+    D -->|Yes| E[Return error: code immutable]
+    D -->|No| F{Name provided and non-empty?}
+    F -->|No| G[Return error: name required]
+    F -->|Yes| H[Update node name]
+    H --> I[Return updated node]
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: Specified node ID does not exist
+- **CODE_IMMUTABLE**: Attempt to change the node code
+- **MISSING_REQUIRED_FIELDS**: Name not provided or empty

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

@@ -0,0 +1,60 @@
+# Item Lifecycle
+
+## Overview
+
+Items are the fundamental SKU-level entity in the ERP system — the sellable, purchasable, and trackable unit. Each item has its own lifecycle state machine, unique SKU identifier, and optional barcode. Items manage their unit of measure independently.
+
+Items can be created in DRAFT or ACTIVE status. DRAFT items require explicit activation before they can participate in transactions.
+
+## Business Purpose
+
+Items serve as the universal SKU entity across the ERP system. Downstream domains reference items as the fundamental tradeable/trackable unit:
+
+- Sales module creates order lines linked to Items
+- Inventory module tracks stock quantities per Item
+- Purchasing module creates purchase order lines linked to Items
+- Manufacturing module references Items in Bill of Materials
+
+The lifecycle state machine ensures:
+
+- Items are reviewed before becoming transactionally available (DRAFT → ACTIVE)
+- Discontinued items are preserved for historical reference (ACTIVE → INACTIVE)
+- Previously discontinued items can return to active use (INACTIVE → ACTIVE)
+- Only DRAFT items can be permanently deleted; ACTIVE/INACTIVE items are preserved for audit trails
+
+## Process Flow
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createItem (draft)
+    [*] --> Active: createItem (active)
+    Draft --> Active: activateItem
+    Active --> Inactive: deactivateItem
+    Inactive --> Active: reactivateItem
+    Draft --> [*]: deleteItem
+```
+
+## Scenario Patterns
+
+- **New Item**: An item is created with a unique SKU, name, UoM, and optional barcode
+- **Draft Item Review**: Items created in DRAFT status are reviewed, barcodes corrected, and activated
+- **Item Deactivation**: A specific SKU is discontinued while other items remain active
+- **Item Reactivation**: A previously discontinued SKU is brought back into active use (INACTIVE → ACTIVE)
+- **Draft Item Cleanup**: Unwanted items in DRAFT status are deleted before activation
+- **SKU Assignment**: Each item receives a globally unique SKU that is immutable once assigned
+
+## Test Cases
+
+- Item lifecycle follows DRAFT → ACTIVE ↔ INACTIVE state machine
+- Items can be created in either DRAFT or ACTIVE status
+- SKU is required, globally unique, and immutable after assignment
+- Barcode must be unique when provided, can be updated
+- Only DRAFT items can be deleted; ACTIVE and INACTIVE items cannot
+- Only ACTIVE items can be referenced in new transactions (sales orders, purchase orders)
+- Items can be activated, deactivated, and reactivated individually
+- Item UoM can be updated in DRAFT status; once activated, UoM is locked to preserve transaction consistency
+
+## Reference Links
+
+- [Oracle Item Master](https://docs.oracle.com/en/cloud/saas/supply-chain-and-manufacturing/25a/fammi/define-items-and-item-structures.html)
+- [NetSuite Item Master Data](https://www.netsuite.com/portal/resource/articles/inventory-management/item-master-data.shtml)

package/src/modules/item-management/docs/features/item-taxonomy.md

@@ -0,0 +1,65 @@
+# Item Taxonomy
+
+## Overview
+
+Item Taxonomy organizes items using a structured, hierarchical classification system. Taxonomy nodes form a tree where each node can have a parent, creating multi-level classification (e.g., "Electronics > Computers > Laptops"). Items are linked to taxonomy nodes through a many-to-many relationship, allowing a single item to belong to multiple classification branches simultaneously (e.g., both "Electronics > Smartphones" and "Gift Ideas > Tech Gifts").
+
+## Business Purpose
+
+As item catalogs grow, a single flat category structure is insufficient. Item Taxonomy addresses this by:
+
+- Enabling multi-dimensional item classification — an item can belong to multiple taxonomy branches
+- Supporting hierarchical browsing and filtering of large item catalogs
+- Enabling consistent item grouping for operations and reporting
+- Organizing items for different audiences (internal operations, eCommerce, procurement)
+- Providing a flexible foundation for future classification needs without restructuring existing data
+- Stable node identification via globally unique code for API references and integrations
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Create Root Taxonomy Node] --> B[Create Child Node]
+    B --> C{More Levels?}
+    C -->|Yes| B
+    C -->|No| D[Assign Items to Taxonomy Nodes]
+    D --> E{Move Node?}
+    E -->|Yes| F[Validate No Circular Reference]
+    F --> G[Update Parent]
+    G --> H[Children Move With Parent]
+    E -->|No| I{Delete Node?}
+    I -->|Yes| J{Has Children or Item Assignments?}
+    J -->|Yes| K[Block Deletion]
+    J -->|No| L[Delete Node]
+    I -->|No| M[Node Active]
+```
+
+## Scenario Patterns
+
+- **Initial Taxonomy Setup**: Administrator creates root nodes with unique codes (e.g., "electronics", "clothing") and populates child nodes for each classification branch
+- **Deep Hierarchy**: "Clothing > Men > Outerwear > Jackets > Winter Jackets" — five levels deep for detailed classification
+- **Multi-Classification**: A "Bluetooth Headset" item is assigned to both "Electronics > Audio" and "Accessories > Travel" taxonomy nodes simultaneously
+- **Node Reparenting**: "Accessories" node moved from under "Clothing" to a root-level node, all child nodes and item assignments preserved
+- **Taxonomy Standards**: "Electronics" node groups items such as laptops, monitors, and accessories under a common branch for operational consistency
+- **Node Rename**: Administrator renames "Accessories" to "Travel Accessories" to better reflect the node's contents — child nodes and item assignments are unaffected
+- **Node Merge**: Two similar nodes consolidated by moving item assignments from one to the other, then deleting the empty node
+- **Reporting by Taxonomy**: Sales report grouped by top-level taxonomy node shows revenue breakdown across item groups (cross-module dependency: reporting/analytics module consumes taxonomy hierarchy)
+
+## Test Cases
+
+- Node code must be globally unique across all taxonomy nodes
+- Node code is immutable after creation; only the display name can be updated
+- Moving a node under its own descendant should fail (circular reference prevention)
+- Deleting a node with child nodes should be blocked
+- Deleting a node with assigned items should be blocked
+- Root nodes have no parent (null parent reference)
+- An item can be assigned to multiple taxonomy nodes
+- Removing an item-taxonomy assignment does not affect the item or other assignments
+- Duplicate item-taxonomy assignments (same item + same node) should be rejected
+- Node tree depth should have a configurable maximum to prevent excessively deep hierarchies
+
+## Reference Links
+
+- [Akeneo Product Classification](https://docs.akeneo.com/serenity-2025-02/articles/manage-your-categories.html)
+- [Salsify Taxonomy Management](https://www.salsify.com/resources/content/product-taxonomy-management)
+- [Odoo Product Categories](https://www.odoo.com/documentation/19.0/applications/inventory_and_mrp/inventory/product_management.html)

package/src/modules/item-management/docs/models/ItemTaxonomyAssignment.md

@@ -0,0 +1,36 @@
+# ItemTaxonomyAssignment
+
+## Description
+
+ItemTaxonomyAssignment is a join entity that links an Item to a TaxonomyNode, enabling many-to-many classification. A single item can belong to multiple taxonomy branches simultaneously (e.g., both "Electronics > Smartphones" and "Gift Ideas > Tech Gifts"), and a single taxonomy node can have multiple items assigned.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [assignItemToTaxonomy](../commands/AssignItemToTaxonomy.md) - Link an item to a taxonomy node
+- [removeItemFromTaxonomy](../commands/RemoveItemFromTaxonomy.md) - Remove a link between an item and a taxonomy node
+
+### Query Definitions
+
+- [GetItemTaxonomyAssignment](../queries/GetItemTaxonomyAssignment.md) - Retrieve an assignment by itemId and taxonomyNodeId
+- [GetTaxonomyNodeAssignments](../queries/GetTaxonomyNodeAssignments.md) - Retrieve item assignments for a given taxonomy node
+
+### Models
+
+- ItemTaxonomyAssignment
+
+### Invariants
+
+- The combination of item and taxonomy node must be unique (no duplicate assignments)
+- The referenced item must exist
+- The referenced taxonomy node must exist
+
+### Relationships
+
+- **References Item**: Each assignment references exactly one Item
+- **References TaxonomyNode**: Each assignment references exactly one TaxonomyNode

package/src/modules/item-management/docs/models/TaxonomyNode.md

@@ -0,0 +1,47 @@
+# TaxonomyNode
+
+## Description
+
+TaxonomyNode represents a single node in a hierarchical classification tree used to organize items. Each node has a globally unique code, a display name, and an optional parent reference that defines its position in the tree. Root nodes have no parent. Nodes can be reparented to restructure the tree, and children move with their parent.
+
+Examples: "electronics", "electronics > computers", "electronics > computers > laptops".
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createTaxonomyNode](../commands/CreateTaxonomyNode.md) - Create a new root or child taxonomy node
+- [updateTaxonomyNode](../commands/UpdateTaxonomyNode.md) - Update the display name of an existing node
+- [moveTaxonomyNode](../commands/MoveTaxonomyNode.md) - Reparent a node within the tree
+- [deleteTaxonomyNode](../commands/DeleteTaxonomyNode.md) - Delete a leaf node with no item assignments
+
+### Query Definitions
+
+- [GetTaxonomyNode](../queries/GetTaxonomyNode.md) - Retrieve a taxonomy node by id or code
+- [GetTaxonomyNodeChildren](../queries/GetTaxonomyNodeChildren.md) - Retrieve direct child nodes of a given node
+- [CalculateNodeDepth](../queries/CalculateNodeDepth.md) - Calculate the depth of a node from root by walking the ancestor chain
+- [CalculateSubtreeDepth](../queries/CalculateSubtreeDepth.md) - Recursively calculate the maximum depth of a node's subtree
+- [DetectCircularReference](../queries/DetectCircularReference.md) - Validate that reparenting would not create a cycle
+
+### Models
+
+- TaxonomyNode
+
+### Invariants
+
+- Node code must be globally unique across all taxonomy nodes
+- Node code is immutable after creation — it cannot be changed once assigned
+- Root nodes have a null parent reference
+- A node cannot be moved under its own descendant (circular reference prevention)
+- Node tree depth has a configurable maximum (default 10) to prevent excessively deep hierarchies
+- A node with child nodes cannot be deleted
+- A node with assigned items cannot be deleted
+
+### Relationships
+
+- **Self-Referential Parent-Child**: Each node optionally references another TaxonomyNode as its parent, forming a tree
+- **Referenced By Item Assignments**: TaxonomyNodes are linked to Items via ItemTaxonomyAssignment (many-to-many)

package/src/modules/item-management/docs/models/item.md

@@ -0,0 +1,59 @@
+# item
+
+## Description
+
+Item is the fundamental SKU-level entity in the ERP system — the sellable, purchasable, and trackable unit referenced by all downstream modules (Sales, Purchasing, Inventory, Manufacturing). Each item has a lifecycle state machine (DRAFT → ACTIVE ↔ INACTIVE), a globally unique SKU identifier, an optional barcode, and an assigned unit of measure.
+
+Items can be created in either DRAFT or ACTIVE status. DRAFT items require explicit activation before participating in transactions.
+
+## Domain Model Definitions
+
+### Model type
+
+Stateful
+
+#### State Transitions
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft: createItem (draft)
+    [*] --> Active: createItem (active)
+    Draft --> Active: activateItem
+    Active --> Inactive: deactivateItem
+    Inactive --> Active: reactivateItem
+    Draft --> [*]: deleteItem
+```
+
+### Command Definitions
+
+- [createItem](../commands/CreateItem.md) - Create a new item in DRAFT or ACTIVE status
+- [updateItem](../commands/UpdateItem.md) - Update mutable fields (name, barcode, UoM) of an existing item
+- [activateItem](../commands/ActivateItem.md) - Transition item from DRAFT to ACTIVE
+- [deactivateItem](../commands/DeactivateItem.md) - Transition item from ACTIVE to INACTIVE
+- [reactivateItem](../commands/ReactivateItem.md) - Transition item from INACTIVE to ACTIVE
+- [deleteItem](../commands/DeleteItem.md) - Permanently delete a DRAFT item
+
+### Query Definitions
+
+- [GetItem](../queries/GetItem.md) - Retrieve an item by id, sku, or barcode
+
+### Models
+
+- Item
+
+### Invariants
+
+- SKU is required and must be globally unique across all items regardless of status
+- SKU is immutable after assignment (cannot be changed once set)
+- Barcode must be unique across all items when provided
+- Barcode can be updated after creation
+- Only DRAFT items can be deleted; ACTIVE and INACTIVE items are preserved for audit trails
+- Only ACTIVE items can be referenced in new transactions (sales orders, purchase orders)
+- Name is required at creation time
+- UoM can be updated only in DRAFT status — once activated, UoM is locked to preserve transaction consistency
+
+### Relationships
+
+- **References Unit**: Each item references a Unit from the primitives module as its unit of measure
+- **Referenced By Taxonomy Assignments**: Items are linked to TaxonomyNodes via ItemTaxonomyAssignment (many-to-many)
+- **Referenced By Downstream Modules**: Items are referenced by Sales, Purchasing, Inventory, and Manufacturing modules

package/src/modules/item-management/docs/queries/CalculateNodeDepth.md

@@ -0,0 +1,36 @@
+# CalculateNodeDepth
+
+## Overview
+
+CalculateNodeDepth determines the depth of a taxonomy node in the tree hierarchy by walking up the ancestor chain from a given node to the root. Depth is defined as the number of nodes in the path from root to the target node (root = depth 1). This is essential for enforcing maximum depth constraints when creating or moving taxonomy nodes.
+
+## Business Rules
+
+- Depth is calculated by traversing parentId references from the target node up to the root
+- Root nodes (parentId = null) have depth 1
+- Each additional ancestor increments the depth by 1
+- The traversal stops when a node with parentId = null is reached or a parent is not found
+- Used together with maxDepth parameter (default: 10) to enforce tree depth limits
+
+## Process Flow
+
+```mermaid
+flowchart TD
+    A[Receive nodeId] --> B[Initialize depth = 1, currentId = nodeId]
+    B --> C[SELECT node where id = currentId]
+    C --> D{Node found?}
+    D -->|No| E[Return current depth]
+    D -->|Yes| F{parentId is null?}
+    F -->|Yes| E
+    F -->|No| G[Increment depth]
+    G --> H[Set currentId = parentId]
+    H --> C
+```
+
+## External Dependencies
+
+- None
+
+## Error Scenarios
+
+- **NODE_NOT_FOUND**: The starting node or an ancestor in the chain is not found — traversal stops and returns partial depth