FLOW MASON
Problem-Solving Guide

How to Think FlowMason

A comprehensive visual guide to transforming any problem into a working pipeline. Master the mental models, patterns, and decision processes used by pipeline architects.

The Core Mental Model

🎯 Problem "I need to..." 🔍 Decompose Break into steps 🧩 Map Choose components 🔗 Connect Wire dependencies 🚀 Pipeline Working solution

Every complex task is just a series of simple steps connected by data flow.

Your job: identify the steps, pick the right component for each, and wire them together.

Mental Models for Pipeline Thinking

Use these analogies to reason about your pipelines

The Assembly Line

Think of your pipeline as a factory assembly line. Raw materials (input) enter, pass through stations (stages), and finished products (output) emerge.

Input → Station 1 → Station 2 → Station 3 → Output
💡 Each station adds value. Stations can run in parallel if they work on independent parts.

The River Delta

Data flows like water. It can split into parallel streams, be filtered, and merge back together.

→→→ [process A] →→→ →→ →→→ [merge] →→→ →→→ [process B] →→→
💡 Look for natural split and merge points. What can flow independently?

The Kitchen

Like cooking a complex meal. Some things prep in parallel, some must be sequential, some need quality checks before proceeding.

Prep vegetables (parallel) → Cook main (sequential) → Taste test (conditional) → Plate
💡 What can be prepped ahead? What's the critical path? Where are the quality gates?

The 6-Step Design Process

Follow this systematic approach for any pipeline you need to build

1 Define Your Goal
2 Identify Your Inputs
3 Decompose Into Steps
4 Choose Components
5 Map Dependencies
6 Build & Iterate
1

Define Your Goal

What outcome do you want?

Start with the end in mind. Clearly articulate what the pipeline should produce. This becomes your north star for every decision.

🧠 Ask Yourself

? What problem am I solving?
? What does success look like?
? What format should the output be in?
? Who or what will consume this output?

📋 Examples

Input:
Raw customer feedback
Output:
Sentiment analysis + categorization
Why:
Need to route to right team
Input:
Blog topic idea
Output:
Published-ready article
Why:
Content automation
Input:
API response data
Output:
Validated, transformed records
Why:
ETL process

⚠️ Common Mistakes to Avoid

  • ✗ Vague goals like 'process the data'
  • ✗ Multiple unrelated outputs from one pipeline
  • ✗ Not considering the consumer of the output
💡
Pro Tip: Write it down: 'Given [specific input], I want [specific output] because [reason]'
2

Identify Your Inputs

What data are you starting with?

Document everything you're feeding into the pipeline. Be specific about structure, types, and what's required vs optional. This becomes your input_schema.

🧠 Ask Yourself

? What data do I have available?
? What format is it in? (JSON, text, array, etc.)
? Which fields are required vs optional?
? What are the constraints? (length, format, etc.)

📥 Common Input Types

📝
Text/String
Documents, prompts, messages
📊
Structured Data
JSON objects, form data, records
📚
Arrays/Lists
Collection of items to process
🌐
External Sources
API endpoints, database queries

⚠️ Common Mistakes to Avoid

  • ✗ Accepting 'any' without validation
  • ✗ Not documenting required fields
  • ✗ Ignoring edge cases (empty, null, very long)
💡
Pro Tip: Create your input schema FIRST - it forces clarity about what you actually need
3

Decompose Into Steps

What transformations are needed?

Break the journey from input to output into discrete, atomic operations. Each step should do ONE thing well. Think of it as assembly line stations.

🧠 Ask Yourself

? If I had to explain this to a human, what would the steps be?
? Which steps require intelligence (AI) vs pure logic?
? Can any steps run in parallel (independent of each other)?
? What's the minimum viable path?

🔬 Example Decomposition

Problem: Generate a personalized product recommendation email
Bad Approach

One big AI prompt that does everything

Good Approach
  • → 1. Fetch user purchase history
  • → 2. Analyze preferences (AI)
  • → 3. Get matching products from catalog
  • → 4. Rank products for user (AI)
  • → 5. Generate personalized email copy (AI)
  • → 6. Format as HTML template

⚠️ Common Mistakes to Avoid

  • ✗ Mega-prompts that try to do everything
  • ✗ Steps with unclear boundaries
  • ✗ Mixing AI and data tasks unnecessarily
💡
Pro Tip: If a step description has 'and' in it, it should probably be two steps
4

Choose Components

Which FlowMason component fits each step?

Map each step from your decomposition to the right component type. This is where understanding the three categories is crucial.

🧩 Component Categories

🧠
AI Nodes

When you need understanding, creativity, or generation

generator Generate text, analyze, summarize, extract
critic Evaluate and score content
improver Refine based on feedback
selector Choose best from options
synthesizer Combine multiple inputs
⚙️
Operators

When you need deterministic, repeatable logic

http_request Call external APIs
json_transform Reshape data with JMESPath
filter Filter arrays by condition
schema_validate Validate against JSON Schema
variable_set Store values for reuse
logger Debug output at any point
🔀
Control Flow

When you need branching, looping, or error handling

conditional If/else branching
router Switch/case multi-path
foreach Loop over array items
trycatch Error handling with fallback
subpipeline Call another pipeline
💡
Pro Tip: When in doubt: Does it need 'thinking'? → Node. Just data manipulation? → Operator.
5

Map Dependencies

What depends on what?

Draw the connections between stages. This creates your DAG (Directed Acyclic Graph). Stages without dependencies run in parallel automatically.

📐 Dependency Rules

📥 Add depends_on when you need data from another stage
⚡ No depends_on = runs immediately in parallel
⏳ Multiple dependencies = waits for ALL to complete
🔗 Reference upstream data with {{stages.id.output}}
💡
Pro Tip: Draw your DAG on paper first. It reveals parallelization opportunities and missing connections.
6

Build & Iterate

Does it work?

Start minimal, test incrementally, and expand. Don't try to build the complete pipeline at once.

🏗️ Build in Phases

1 Skeleton

1-2 stages, happy path only

Does basic flow work?

2 Core Logic

Add remaining stages

Does each component work?

3 Error Handling

Add trycatch, validation

What can go wrong?

4 Optimization

Add parallelism, caching

Can it be faster?

💡
Pro Tip: Use FlowMason Studio's debugger to step through execution and inspect data at each stage

Component Decision Flowchart

Not sure which component to use? Follow this visual decision tree:

Start Here Needs AI/LLM? (understanding, creativity) Yes 🧠 AI Node generator, critic, improver No Transform data? (reshape, filter, validate) Yes ⚙️ Operator json_transform, filter No Branching logic? (if/else, switch) Yes 🔀 Control Flow conditional, router No Loop/iterate? Yes foreach No API call? http_request
1 Does this step require understanding, creativity, or language?
Yes →
Use an AI Node
generatorcriticimprover
No → Continue to next question
2 Does it transform or manipulate data structure?
Yes →
Use an Operator
json_transformfilterschema_validate
No → Continue to next question
3 Does it need to branch based on conditions?
Yes →
Use Control Flow
conditionalrouter
No → Continue to next question
4 Does it process a collection of items?
Yes →
Use foreach loop
foreach
No → Continue to next question
5 Does it call an external API or service?
Yes →
Use http_request
http_request
No → Continue to next question
6 Does it need error handling or fallback?
Yes →
Use trycatch
trycatch
No → Reconsider if this step is needed

DAG Patterns Visualized

Master these fundamental patterns to wire any pipeline

Sequential Chain

Each stage depends on the previous. Use when order matters and each step needs the previous result.

┌───┐ ┌───┐ ┌───┐ │ A │───▶│ B │───▶│ C │ └───┘ └───┘ └───┘
When: Processing pipeline, refinement loops, step-by-step transformations
View code 
"stage_b": { "depends_on": ["stage_a"] }
"stage_c": { "depends_on": ["stage_b"] }

Parallel Execution

Independent stages run simultaneously. Use when stages don't need each other's data.

┌───┐ │ B │ ┌───┐ ╱└───┘╲ ┌───┐ │ A │──▶ ──▶│ D │ └───┘ ╲┌───┐╱ └───┘ │ C │ └───┘
When: Multiple independent operations, fetching from different sources
View code 
"stage_b": { "depends_on": ["stage_a"] }
"stage_c": { "depends_on": ["stage_a"] }
"stage_d": { "depends_on": ["stage_b", "stage_c"] }

Fan-Out

One input feeds multiple parallel processes. Use when one result needs different processing paths.

┌───┐ ╱│ B │ ┌───┐──▶ └───┘ │ A │──▶ ┌───┐ └───┘──▶╲│ C │ └───┘ ┌───┐ │ D │ └───┘
When: Multi-format output, A/B testing, broadcasting
View code 
"stage_b": { "depends_on": ["stage_a"] }
"stage_c": { "depends_on": ["stage_a"] }
"stage_d": { "depends_on": ["stage_a"] }

Fan-In (Aggregation)

Multiple stages feed into one. Use when you need to combine results from parallel work.

┌───┐ │ A │─╲ └───┘ ╲ ┌───┐ ┌───┐──▶│ D │ │ B │──╱ └───┘ └───┘ ╱ ┌───┐╱ │ C │ └───┘
When: Merging results, voting systems, collecting from multiple sources
View code 
"stage_d": { "depends_on": ["stage_a", "stage_b", "stage_c"] }

Diamond Pattern

Fork and join. Use when you need parallel processing with a merge at the end.

┌───┐ ╱│ B │╲ ┌───┐──▶ └───┘ ╲ ┌───┐ │ A │ ▶│ D │ └───┘──▶ ┌───┐ ╱ └───┘ ╲│ C │╱ └───┘
When: Compare approaches, process then aggregate, parallel enrichment
View code 
"stage_b": { "depends_on": ["stage_a"] }
"stage_c": { "depends_on": ["stage_a"] }
"stage_d": { "depends_on": ["stage_b", "stage_c"] }

Conditional Branch

Route to different paths based on conditions. Use the conditional or router component.

┌───┐ ╱│ B │ (if true) ┌───┐──◇ └───┘ │ A │ ? └───┘──◇ ┌───┐ ╲│ C │ (if false) └───┘
When: Different handling based on type, quality gates, error paths
View code 
"router": {
  "component_type": "conditional",
  "config": {
    "condition": "{{stages.a.output.score}} > 0.8",
    "true_branch": ["stage_b"],
    "false_branch": ["stage_c"]
  }
}

Complete Example: Thinking Through a Real Pipeline

Watch the mental process of designing a pipeline from scratch

🎯

The Problem

Build an AI-powered customer support ticket classifier and responder

✅

Goal Statement

Given a support ticket, classify its type and urgency, then generate an appropriate response draft

📥 Sample Input

{
  "subject": "Can't login to my account",
  "body": "I've been trying to login for 2 hours. Keep getting 'invalid password' but I know my password is correct. This is urgent - I have a deadline!",
  "customer_email": "[email protected]",
  "timestamp": "2024-01-15T10:30:00Z"
}

🧠 The Thinking Process

1
What's my goal?
Classify the ticket (type + urgency) and generate a helpful response draft
2
What's my input?
A ticket object with subject, body, email, and timestamp
3
What steps are needed?
1) Classify type, 2) Assess urgency, 3) Generate response based on both
4
Which components?
All three steps need AI understanding → Use generator nodes
5
What are the dependencies?
Classify and urgency can run in parallel. Response needs both.

📊 Resulting Pipeline DAG

📥 Input ticket data 🧠 classify_type generator 🧠 assess_urgency generator ⚡ parallel 🧠 generate_response generator (depends on both) 📤 Output

📋 Stage Configurations

generator classify_type — Determine ticket category 
{
  "prompt": "Classify this support ticket into ONE category: billing, technical, account, general.\n\nSubject: {{input.subject}}\nBody: {{input.body}}\n\nRespond with JSON: { \"type\": \"...\" }",
  "temperature": 0.1
}
generator assess_urgency — Determine urgency level 
{
  "prompt": "Assess the urgency of this support ticket: low, medium, high, critical.\nConsider: customer frustration, time sensitivity, business impact.\n\nSubject: {{input.subject}}\nBody: {{input.body}}\n\nRespond with JSON: { \"urgency\": \"...\", \"reasoning\": \"...\" }",
  "temperature": 0.1
}
generator generate_response — Generate appropriate response depends_on: [classify_type, assess_urgency] 
{
  "prompt": "Generate a helpful customer support response.\n\nTicket Type: {{stages.classify_type.output.type}}\nUrgency: {{stages.assess_urgency.output.urgency}}\nOriginal Subject: {{input.subject}}\nOriginal Body: {{input.body}}\n\nBe empathetic, acknowledge the issue, and provide next steps.",
  "temperature": 0.7
}

📤 Expected Output

{
  "classification": {
    "type": "account",
    "urgency": "high"
  },
  "response": "I completely understand your frustration, and I'm sorry you're experiencing login issues right before an important deadline..."
}

Quick Reference: Component Cheat Sheet

Keep this visual guide handy when designing pipelines

🧠

AI Nodes

When you need intelligence

generator

Create text, analyze, summarize, extract info

critic

Score and evaluate content quality

improver

Refine content based on feedback

selector

Choose best from multiple options

⚙️

Operators

Deterministic data processing

http_request

Call external APIs and services

json_transform

Reshape data with JMESPath

filter

Filter arrays by condition

schema_validate

Validate JSON structure

🔀

Control Flow

Branching and looping

conditional

If/else branching

router

Switch/case multi-routing

foreach

Iterate over collections

trycatch

Error handling with fallback

Ready to build your pipeline?

Use the Pipeline Wizard to apply these concepts with guided help.

🧙 Launch Wizard Read Documentation View Demo Pipelines