Fundamentals

Workflows 101

Learn the fundamentals of building AI workflows. Understand how nodes, edges, execution order, and data flow work together to create powerful automation.

⏱️ 15 minutes•Beginner-friendly

What is a Workflow?

A workflow is a visual representation of an automated process. In TopFlow, workflows are made up of nodes (boxes that perform actions) connected by edges (arrows that show data flow).

Think of it like a flowchart for AI automation:

Nodes = Steps in your process (e.g., "generate text", "call API", "check condition")
Edges = Data flowing between steps (e.g., "output from step 1 becomes input for step 2")
Execution = Running the workflow from start to finish

Real-World Example: Threat Intelligence Report

Fetch threat data - HTTP Request node calls threat intelligence API

Analyze threats - Text Model node (GPT-4) analyzes severity and impact

Generate report - Structured Output node formats as JSON

Send alert - Conditional node checks if critical, then HTTP Request posts to Slack

Anatomy of a Workflow

Every TopFlow workflow has three core components:

1. Nodes (Actions)

Building blocks that perform specific tasks

12 node types available:

Entry/Exit

Start, End

AI Nodes

Text Model, Embedding, Image Gen, Audio

Data Processing

Prompt, JavaScript, Structured Output

Flow Control

Conditional, HTTP Request, Tool

Node properties:

Type - What the node does (e.g., textModel, httpRequest)
Data - Configuration settings (e.g., model: "gpt-4", temperature: 0.7)
Inputs - Data received from upstream nodes
Outputs - Data sent to downstream nodes

2. Edges (Connections)

Arrows that define data flow between nodes

Edges connect nodes and determine:

Execution order - Which nodes run before others (topological sorting)
Data flow - How outputs from one node become inputs to another
Conditional branching - For Conditional nodes, edges can be "true" or "false" paths

Edge structure:

{
  id: "edge-1",
  source: "node-start",    // Which node sends data
  target: "node-textModel", // Which node receives data
  sourceHandle: "true"      // Optional: for conditional branching
}

Important: You cannot create cycles (circular loops). TopFlow will detect and block workflows with cycles.

3. Workflow Graph

The complete structure combining nodes and edges

A workflow is a directed acyclic graph (DAG):

Directed - Edges have direction (data flows one way)
Acyclic - No loops or cycles allowed
Graph - Nodes connected by edges

{
  nodes: [
    { id: "start", type: "start", data: { input: "Analyze security logs" } },
    { id: "text", type: "textModel", data: { model: "gpt-4" } },
    { id: "end", type: "end", data: {} }
  ],
  edges: [
    { id: "e1", source: "start", target: "text" },
    { id: "e2", source: "text", target: "end" }
  ]
}

Execution Model

Understanding how TopFlow executes workflows is key to building effective automation.

Topological Execution Order

Nodes execute in dependency order, not creation order

TopFlow automatically determines execution order using topological sorting:

Find entry nodes - Nodes with no incoming edges (usually Start node)
Execute node - Run the node's logic
Store result - Save output for downstream nodes
Find next nodes - Nodes whose dependencies are all complete
Repeat - Until all nodes executed

Example Execution

Start → outputs "Analyze threat data"

HTTP Request → fetches threat intel (receives Start's output)

Text Model → analyzes data (receives HTTP's output)

End → collects final result

Sequential vs. Parallel Execution

How TopFlow handles branching and merging

Sequential: Nodes execute one at a time in topological order.

Conceptual parallelism: If multiple nodes have all dependencies met, they could run in parallel. However, TopFlow currently executes them sequentially for simplicity and predictability.

Note: While the visual builder shows parallel branches, execution is sequential. Future versions may support true parallel execution.

Conditional Branching

How if/else logic works in workflows

Conditional nodes have two output handles:

"true" handle - Edge followed if condition evaluates to true
"false" handle - Edge followed if condition evaluates to false

// Conditional node checks severity
condition: "output.includes('CRITICAL')"

// Two edges from this node:
{ source: "conditional", target: "alert-slack", sourceHandle: "true" }  // High severity
{ source: "conditional", target: "log-only", sourceHandle: "false" }    // Normal severity

Only matching edges are followed. If condition is true, only the "true" edge executes. The "false" branch is skipped entirely.

Data Flow & Variables

Understanding how data moves through your workflow is essential for building complex automation.

Variable Interpolation

Using outputs from upstream nodes

Access upstream outputs using $input1, $input2, etc.

When a node receives multiple inputs, they're numbered by the X position of source nodes (left to right):

// Node "merge" receives two inputs:
// - From node "fetch-data" (X: 100)
// - From node "user-prompt" (X: 200)

// In the merge node's prompt:
"Combine this data: $input1 with user request: $input2"

// Runtime replacement:
"Combine this data: [API response] with user request: [user input]"

Where you can use variables:

Prompt nodes - Template prompts with dynamic data
HTTP Request nodes - Dynamic URLs and request bodies
JavaScript nodes - Access via input1, input2 variables
Conditional nodes - Reference in condition expressions

Data Transformations

Processing and formatting data between nodes

Common transformation patterns:

Extract JSON fields

// JavaScript node
const data = JSON.parse(input1)
return data.threats.filter(t => t.severity === "HIGH")

Format for AI prompt

// Prompt node
Analyze these security events:

$input1

Provide: severity, affected systems, recommended actions

Structured output parsing

// Structured Output node with Zod schema
{
  threatLevel: z.enum(["LOW", "MEDIUM", "HIGH", "CRITICAL"]),
  affectedSystems: z.array(z.string()),
  recommendations: z.array(z.string())
}

Common Workflow Patterns

Learn these proven patterns to solve common automation challenges.

Pattern 1: API → AI Analysis → Structured Output

Fetch data, analyze with AI, return formatted results

Start → Provides API endpoint URL

HTTP Request → Fetches data from external API

Text Model → Analyzes data with GPT-4/Claude

Structured Output → Validates and formats as JSON schema

End → Returns formatted result

Use case: Security log analysis, market research, data enrichment

Pattern 2: Conditional Alert Routing

Route based on severity or other criteria

Start → Security event data

Text Model → Classify severity (LOW, MEDIUM, HIGH, CRITICAL)

Conditional → Check if severity === "CRITICAL"

If TRUE → HTTP Request to PagerDuty (immediate page)

If FALSE → HTTP Request to Slack (notification only)

Use case: Alert routing, approval workflows, data filtering

Pattern 3: Multi-Step Enrichment

Enhance data through multiple AI calls

Start → Raw customer feedback

Text Model (GPT-4) → Extract sentiment (positive/negative/neutral)

Text Model (GPT-4) → Identify key topics and themes

JavaScript → Merge sentiment + topics into single object

End → Return enriched data

Use case: Data enrichment, multi-modal analysis, progressive refinement

Validation & Errors

TopFlow validates your workflow before execution to catch errors early.

Errors (Block Execution)

Must be fixed before workflow can run

❌
Cycle detected - Workflow has circular dependency
❌
Missing start/end node - Must have exactly one Start and one End
❌
Orphan nodes - Nodes not connected to main flow
❌
Missing required config - Empty model, prompt, or URL
❌
SSRF blocked - HTTP Request targeting localhost or internal IP
❌
Missing API key - Provider key not configured in settings

Warnings (Don't Block)

Recommendations to improve security or performance

⚠️
PII detected - Prompt contains potential personal data (email, SSN)
⚠️
High temperature - Using temperature > 1.5 may produce inconsistent results
⚠️
Large maxTokens - Setting > 2000 may slow execution
⚠️
Prompt injection pattern - Input contains suspicious phrases ("ignore previous instructions")

Validation Score

Security and quality rating (0-100)

TopFlow assigns a grade based on errors and warnings:

90-100

Excellent - Production ready

80-89

Good - Minor improvements needed

70-79

Acceptable - Review warnings

60-69

Poor - Significant issues

Below 60

Failed - Cannot execute

Best Practices

Follow these guidelines to build robust, secure, and maintainable workflows.

Do's

✓
Start simple - Build incrementally, test each node
✓
Use descriptive node names - "Analyze Security Logs" not "Text Model 1"
✓
Validate early - Check validation panel before execution
✓
Export regularly - Download TypeScript backups
✓
Use Structured Output - For consistent, parseable results
✓
Test with demo mode first - Before using real API keys

Don'ts

✗
Don't create cycles - Circular dependencies crash workflows
✗
Don't hardcode secrets - Use API Settings for keys
✗
Don't ignore SSRF warnings - They block malicious URLs
✗
Don't use high temperature for facts - Use 0.1-0.3 for accuracy
✗
Don't skip validation - Fix all errors before execution
✗
Don't build on incognito - localStorage lost on close

Next Steps

Now that you understand the fundamentals, dive deeper into specific topics:

Build Your First Workflow

Step-by-step tutorial

Quick Start

Explore Node Types

All 12 nodes explained

Node Reference

Security Validations

12 security checks

Learn Security