2025-11-17: Segment/Folder Unification Design

Date: 2025-11-17 | JIRA: DEVAI-417

Problem Statement

The previous command structure treated folders and segments as separate entities, creating a fragmented user experience when navigating hierarchical segment structures.

Limitations addressed:

• tdx segments listed only child segments, not folders
• Separate commands for folder operations
• No support for nested folder paths
• No context/navigation system
• No tree view for hierarchy

Design Goals

1. Unified navigation model - Folders and segments as a cohesive hierarchy
2. Context-aware operations - Work within a specific folder context
3. Path-based addressing - Multi-level paths like parent/folder1/folder2/item
4. Intuitive UX - Similar to file system navigation

Hierarchy Model

Parent Segment (Audience)
├── Folders (organizational containers)
│   └── Folders (support nesting)
└── Child Segments (filtered subsets with rules)
    └── Can be placed in folders

Command Structure

Navigation & Listing

# List contents (folders + segments)
tdx segments              # Current level only
tdx segments -r           # Recursive tree view

# Context management
tdx segment use <path>    # Switch context
tdx context               # Show current context

Resource Operations

# Auto-detect type from path
tdx segment show <path>
tdx segment create <path>
tdx segment update <path>
tdx segment delete <path>

# Segment-specific
tdx segment sql <path>
tdx segment fields [parent]

Path Syntax

# Absolute paths
tdx segment show "My Audience/Marketing/Email Subscribers"

# Relative paths (from context)
tdx segment use "My Audience/Marketing"
tdx segment show "Email Subscribers"

# Navigation
tdx segment use "Campaigns"     # Into subfolder
tdx segment use ..              # Up to parent
tdx segment use /               # Back to root

Type Auto-Detection

Commands automatically detect if path is folder or segment. If ambiguous (same name exists), prompts user for selection.

Output Format

Context: My Audience

📁 Marketing/
  📁 Campaigns/
    🎯 Email Q1 (5,234)
    🎯 Email Q2 (6,122)
  🎯 Email Subscribers (15,000)
📁 Sales/
  🎯 High Value (2,100)
🎯 All Users (50,000)

Key Changes

Old Behavior	New Behavior
tdx segments lists only segments	Lists folders + segments
parent/child (2 levels)	parent/folder/item (unlimited)
No context system	Context maintained via segment use