> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryhamsa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Advanced Features

> Nested data, enums, path selector, and technical architecture

## Nested Data Structures

Variables can be objects or arrays with nested structure.

**Object example:**

```typescript theme={null}
{
  name: "user_profile",
  dataType: "object",
  properties: [
    { name: "first_name", dataType: "string" },
    { name: "last_name", dataType: "string" },
    { name: "age", dataType: "number" },
    { name: "is_verified", dataType: "boolean" }
  ]
}
```

**Array example:**

```typescript theme={null}
{
  name: "order_items",
  dataType: "array",
  item: {
    name: "item",
    dataType: "object",
    properties: [
      { name: "product_id", dataType: "string" },
      { name: "quantity", dataType: "number" },
      { name: "price", dataType: "number" }
    ]
  }
}
```

## Enum Values

Restrict a variable to a fixed set of options:

```typescript theme={null}
{
  name: "appointment_type",
  dataType: "string",
  isEnumEnabled: true,
  enumValues: [
    { value: "consultation", label: "Initial Consultation" },
    { value: "follow_up", label: "Follow-up Visit" },
    { value: "emergency", label: "Emergency Appointment" }
  ]
}
```

**Benefits:** Consistent values, dropdown UI, better AI extraction, clearer validation.

## Variable Usage Tracking

The system can track where variables are used:

* Which nodes reference each variable
* Which fields contain references
* Count per field and last usage

**Use cases:** Find unused variables, impact before deletion, refactoring, dependency view.

## JSONPath Path Selector (Tool Extraction)

For tool nodes, the path selector lets you pick extraction paths from the response instead of typing JSONPath by hand.

**Typical workflow:**

1. **Configure tool** (endpoint, headers, params).
2. **Test tool** (API: “Test Tool”; Web: define expected response).
3. **Add extracted variable** → open path selector.
4. **Browse tree** (expand/collapse, hover for types/values).
5. **Click a field** → JSONPath is filled (e.g. `$.data.user.email`).
6. **Preview** shows the extracted value; save when correct.

**Features:** Test-before-extract (API), tree view, click-to-select, validation against response, preview, array and nested support, clear errors for invalid paths.

**Example:**

```
Tool response has: data.user.email = "customer@example.com"
Path selector: data → user → email (click)
Selected path: $.data.user.email
Extracted value: "customer@example.com"
```

## Technical Architecture

### Store Structure

**Variables store** holds: `extractedVariables`, `systemVariables`, `customVariables`, `referencedVariables`, `nodeAvailabilityCache`, `cacheVersion`, `isRecalculating`, `validationErrors`.

### Key Utilities

* **Variable context**: `getVariableAvailabilityForNode()`, `analyzeFlowExecutionOrder()`, path analysis
* **JSONPath mapper**: `userToBackendPath()` (`$.path` → `result.path`), `backendToUserPath()`
* **Variable detection**: Scan text for `{{...}}`, extract names, validate syntax
* **Context rules**: Pattern-based recommendations and context-aware suggestions

### Integration

Flow builder store, variables store, flow–variables bridge, variable context utils, context rules, template system, validation, UI (panel, inputs, builders).

### Synchronization Flow

```
Flow change (node add/update/delete)
  → Flow–variables bridge
  → syncExtractedVariablesFromNodes()
  → Scan nodes for extractVariables, staticVariables, dtmfInputCapture
  → Update store, invalidate cache
  → UI re-renders
```

See [API Reference](./api-reference) for schemas and file paths, and [Extracted Variables](./extracted-variables) for using the path selector with API vs Web tools.