hierarchical-taxonomies

Hierarchical Taxonomies

Generate and structure a parent/child taxonomy tree. Choose storage schema, validate the hierarchy, export in multiple formats.

When to use

• "Create a product category tree"
• "I need a nested content classification with subcategories"
• "Build a Dewey-style organizational hierarchy"
• "Generate a category / subcategory taxonomy for…"

Inputs to gather

• Domain: What is this hierarchy for?
• Depth: How deep? (2–3 levels typical; >5 is rare)
• Branching factor: Rough average children per node?
• Root: Is there a single root node or multiple top-level categories?
• Schema preference: How to store parent/child relationships?

Procedure

1. Recommend schema: Default to adjacency list (id, parent_id, code, label, description) for most cases (≤10k nodes, simple queries). For deep lookups or range queries, suggest:
   • Materialized path (/electronics/computers/laptops): good for traversal; update-heavy if paths change.
   • Nested set (lft, rgt): efficient range queries; complex to maintain; only if user explicitly asks.
2. Elicit spec using the pattern from generate-from-spec: domain, scope, depth, fields.
3. Generate the hierarchy:
   • Build a tree structure with each node having: code (PK, unique), label, description, parent_code (nullable for roots).
   • For small/standard hierarchies: write directly.
   • For large/specialized: suggest web research or external source (e.g., existing open taxonomies).
4. Validate the tree:
   • Ensure every parent_code resolves to an existing code (no dangling FKs).
   • Detect cycles via depth-first search; fail loudly if found.
   • Check all nodes are reachable from root(s); warn if islands exist.
5. Output:
   • data/<name>/<name>.csv: Flat adjacency-list format (code, parent_code, label, description).
   • data/<name>/tree.json: Nested JSON tree for human review (each node has children array).
   • data/<name>/<name>-materialized-paths.csv (optional): Add path column for materialized-path schema if user requests.
6. Show tree.json to user for review before load.

Output / side effects

• Flat CSV + nested tree.json in data/<name>/.
• Validation report (cycles, islands, dangling refs).

Safety / constraints

• No cycles: DFS check required; cycle detection is non-negotiable.
• Reachability: Warn if the tree has disconnected components.
• Review before load: User must approve the tree structure before any DB insert.