# CreateTaxonomyNode

## Permission Scope

taxonomy

## 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**: Operation would cause the taxonomy subtree to exceed the maximum depth limit

## Test Cases

- returns error when code already exists
- returns error when parent does not exist
- returns error when max depth would be exceeded
- creates a root node
- creates a child node under existing parent
- passes custom fields through to insert