Design Philosophy

1. Flows are Graphs, Not Programs

YFlow flows are graphs, not traditional programs. This distinction is fundamental to how YFlow is designed, authored, executed, and secured.

Understanding this mental model helps avoid common mistakes and explains why YFlow behaves differently from scripting or workflow engines.

YFlow treats the flow as a directed graph expressed as data:

nodes:    
      - start:    
          next: welcome    
         
      - welcome:    
          type: say    
          message: Welcome!    
          next: main_agent    

2. Nodes are Ordered Arrays

In YFlow, nodes are ordered arrays, not unordered collections or independently executing units. This ordering is intentional and foundational to how flows are authored, validated, and traversed.

While flows are graphs at a high level, the contents of a state are evaluated in a defined, linear order.

    nodes:    
      - node_name:    
          type: start | end | say | agent | menu | api | transfer | tools | branch | set    
          # ... type-specific properties    
          next: target_node # simple routing    
          # OR    
          exits: # named exits (API, Transfer)    
            exit_name:    
              next: target_node    

The node name is the map key, making it visually distinct on its own line.

Order Preservation: Using an array guarantees order is preserved through round-trips (YAML → editor → YAML), which is essential for clean diffs and predictable output.

3. Variable Syntax

YFlow uses a simple, explicit, and safe variable syntax to reference data supplied to a flow or produced by nodes. Variable syntax is intentionally constrained to preserve read‑only access, predictability, and security.

Variables allow flows to refer to data, not manipulate it.

YFlow uses a unified {variable} syntax for all variable references:

# API Parameters - variables and constants    
    params:    
      accountId: '{account_id}' # Variable reference    
      pin: '{pin}' # Variable reference    
      action: 'update' # String constant    
      version: 2 # Numeric constant    
      includeDetails: true # Boolean constant    
         
    # Text Interpolation - same syntax in messages and prompts    
    system: 'Help {user_name} with their {account_type} account.'    
    message: 'Your balance is {balance_amount}.'    

Conversion Layer: When importing Customer v2 JSON, the parser converts bare variable names to {variable} syntax. When exporting to JSON, {variable} references in params are converted back to bare names for Customer v2's requestVariables mapping.

YFlow:   params: { accountId: "{account_id}" }    
               ↓ export    
     Customer v2:   requestVariables: { "accountId": "account_id" }    
               ↓ import    
    YFlow:   params: { accountId: "{account_id}" }    

Benefits:

• Consistency - One syntax for all variable references

• Clarity - Easy to distinguish variables ({account_id}) from constants ("update")

• Mixed params - Variables and constants can coexist in the same API call

• Future expression language support - with this syntax, expression language support can be added.

4. Dual Naming: ID + Label

YFlow supports dual naming for key entities—using both a stable ID and a human‑readable label. This design separates machine identity from author intent, enabling safe refactoring, clear readability, and long‑term maintainability.

YFlow uses a dual naming scheme for stable references:

    integrations:    
      banking_api: # ID - immutable, like a variable name    
        label: 'Banking API' # Display name - can change freely    
        type: rest    
        base_url: https://api.bank.com    
        methods:    
          get_balance: # Method ID - immutable    
            label: 'Get Account Balance'    
            http: GET /accounts/{id}/balance    
         
    nodes:    
      - check_balance:    
          type: api    
          integration: banking_api # References the immutable ID    
          method: get_balance # References the immutable ID    

Why this matters:

• References never break - IDs are immutable identifiers (like variable names in code)

• Users can rename freely - Changing the label doesn't affect any references

• Git-friendly - IDs are stable, so diffs are clean

• No UUIDs needed - IDs serve as stable identifiers without cryptic UUIDs

ID Conventions:

• Use snake_case for IDs

• Keep IDs short but descriptive

• IDs should be valid identifiers (letters, numbers, underscores)

Label is optional:

If omitted, the ID is used for display:

integrations:    
      swapi: # ID = "swapi", displayed as "swapi"    
        type: rest    
        base_url: https://swapi.dev