# 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](../command/CreateTaxonomyNode.md) - Create a new root or child taxonomy node
- [updateTaxonomyNode](../command/UpdateTaxonomyNode.md) - Update the display name of an existing node
- [moveTaxonomyNode](../command/MoveTaxonomyNode.md) - Reparent a node within the tree
- [deleteTaxonomyNode](../command/DeleteTaxonomyNode.md) - Delete a leaf node with no item assignments

### Query Definitions

- [GetTaxonomyNode](../query/GetTaxonomyNode.md) - Retrieve a taxonomy node by id or code
- [GetTaxonomyNodeChildren](../query/GetTaxonomyNodeChildren.md) - Retrieve direct child nodes of a given node
- [CalculateNodeDepth](../query/CalculateNodeDepth.md) - Calculate the depth of a node from root by walking the ancestor chain
- [CalculateSubtreeDepth](../query/CalculateSubtreeDepth.md) - Recursively calculate the maximum depth of a node's subtree
- [DetectCircularReference](../query/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)