# Understanding the depth and parentId Fields in the ADHD Idea Type

> Understand the depth and parentId fields in the ADHD Idea type. Learn how these fields track idea hierarchy and enable branching logic for seamless navigation and management.

- Repository: [Udit Akhouri/adhd](https://github.com/UditAkhourii/adhd)
- Tags: api-reference
- Published: 2026-07-30

---

**The `depth` field tracks how many levels an idea sits below the root of a divergence tree, while `parentId` references the immediate ancestor idea that spawned it, together enabling hierarchical traversal and branching logic.**

The **ADHD** (AI-driven Divergence-Heavy Design) tool models brainstorming as a tree of related concepts, where each node is an **Idea** type defined in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts). The `depth` and `parentId` fields serve as the structural backbone of this hierarchy, allowing the system to trace lineage, render visual trees, and prioritize which branches to expand.

## What the depth Field Represents

The `depth` property is a numeric indicator that measures an idea's vertical position within the divergence hierarchy.

- **Value `0`** marks a **root divergence**—the first-level split from the original problem statement with no ancestors.
- **Values `1`, `2`, …** indicate ideas that have been **deepened** one or more levels, representing sub-ideas generated from earlier concepts.

This field serves multiple critical functions in the ADHD engine:

1. **Prioritization** – The system uses depth to identify and expand the most promising branches when running divergence heuristics.
2. **Visualization** – Rendering engines rely on depth values to create indented lists or tree diagrams that show conceptual nesting.
3. **Scoring context** – Deeper ideas often reflect more refined or novel angles, allowing the scorers in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) to weight abstraction levels appropriately.

According to the ADHD source code in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts), the property is declared with the explicit comment `0 = root divergence, 1+ = deepened`【source】.

## What the parentId Field Represents

The `parentId` field stores the `id` of the immediate predecessor from which the current idea was derived.

- **Definition** – It contains the UUID string referencing the parent Idea that spawned this node during the divergence process.
- **Optionality** – This field is deliberately omitted for root ideas (where `depth = 0`) because they have no ancestral node.
- **Traversal** – By following `parentId` references, the engine can reconstruct full ancestry chains for back-tracking and explanation generation.

The `parentId` definition appears alongside `depth` in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts)【source】, forming a lightweight pointer system that avoids storing full object references.

## How depth and parentId Model the Divergence Tree

Together, these two fields create a standard tree structure without circular references:

| Depth | parentId | Meaning |
|-------|----------|---------|
| `0` | omitted | Root idea (no parent) |
| `1` | root's UUID | First-level child of the root |
| `2` | depth-1 idea's UUID | Grandchild (sub-idea of a depth-1 idea) |
| `n` | ancestor's UUID | Further nesting follows the same pattern |

When the engine executes a run via `engine.run(...)`, it instantiates new `Idea` objects by assigning unique `id` values, computing `depth` based on the current recursion level, and recording the `parentId` of the spawning node. Later stages—including scoring, clustering, and deepening—navigate this graph efficiently using these hierarchical markers.

## Working with Hierarchy in Code

### Creating a Root Idea

Root ideas initialize the divergence process with `depth: 0` and no `parentId`:

```typescript
import { v4 as uuidv4 } from "uuid";

const rootIdea = {
  id: uuidv4(),
  frameId: "frame-1",
  text: "Enable voice-controlled navigation",
  depth: 0,          // root divergence
  // parentId omitted intentionally
};

```

### Adding a Deepened Child Idea

Child ideas increment the depth and reference their parent's identifier:

```typescript
const childIdea = {
  id: uuidv4(),
  frameId: "frame-2",
  text: "Integrate with speech-to-text API",
  depth: 1,               // one level deeper than the root
  parentId: rootIdea.id,  // reference to its parent
};

```

### Traversing the Ancestry Chain

To reconstruct the lineage of any idea, map ids to objects and follow the `parentId` pointers:

```typescript
function getAncestors(ideaId: string, ideas: Idea[]): Idea[] {
  const map = new Map(ideas.map(i => [i.id, i]));
  const lineage: Idea[] = [];
  let cur = map.get(ideaId);
  
  while (cur?.parentId) {
    const parent = map.get(cur.parentId);
    if (!parent) break;
    lineage.unshift(parent);
    cur = parent;
  }
  return lineage;
}

```

### Rendering a Visual Tree

The [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) utilities group children by their `parentId` to produce indented output:

```typescript
function renderTree(ideas: Idea[]) {
  const byParent = new Map<string | undefined, Idea[]>();
  
  ideas.forEach(i => {
    const key = i.parentId ?? "root";
    if (!byParent.has(key)) byParent.set(key, []);
    byParent.get(key)!.push(i);
  });

  function render(nodeId: string | undefined, indent = 0) {
    const children = byParent.get(nodeId) ?? [];
    children.forEach(c => {
      console.log(" ".repeat(indent * 2) + "- " + c.text);
      render(c.id, indent + 1);
    });
  }

  render(undefined); // start at roots
}

```

## Key Files Implementing These Fields

| File | Purpose |
|------|---------|
| [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) | Declares the `Idea` interface including `depth` and `parentId` definitions |
| [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) | Orchestrates idea generation and manages branching logic using these fields |
| [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts) | Contains tree visualization utilities that parse the hierarchy |
| [`tests/llm.test.ts`](https://github.com/UditAkhourii/adhd/blob/main/tests/llm.test.ts) | Validates idea creation and hierarchy behavior in the test suite |

## Summary

- **`depth`** indicates vertical position in the divergence tree, where `0` represents root ideas and higher integers represent successive layers of refinement.
- **`parentId`** stores the UUID of the immediate ancestor, omitted only for root nodes to maintain acyclic structure.
- Together they enable **efficient traversal**, **visual rendering**, and **intelligent branching** in the ADHD brainstorming engine.
- The implementation resides primarily in [`src/types.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/types.ts) with consumption across [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) and [`src/render.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/render.ts).

## Frequently Asked Questions

### What happens if parentId references a non-existent idea?

The traversal logic in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) and utility functions like `getAncestors` include null checks that break the chain if a parent lookup fails, preventing runtime errors while potentially logging warnings about orphaned nodes.

### Can an idea have multiple parentId values?

No, the `parentId` field is singular by design. ADHD models strict hierarchical trees rather than directed acyclic graphs (DAGs), ensuring each idea has exactly one lineage path back to a root divergence.

### Why is parentId optional in the TypeScript type?

The field is typed as optional (`parentId?: string`) specifically to accommodate root ideas at `depth: 0`, which logically have no parent. This design choice enforces referential integrity where only non-root nodes carry ancestral pointers.

### How does the engine prevent infinite loops when deepening ideas?

The divergence process in [`src/engine.ts`](https://github.com/UditAkhourii/adhd/blob/main/src/engine.ts) enforces depth limits and tracks visited `id` values during recursion. Since `parentId` references always point to shallower depths (lower numbers), the structure inherently prevents cycles by moving toward the root.