Flows & Visualization

Flows are logical groupings of steps that work together to accomplish specific business goals. They provide structure, visualization, and observability for your multi-language workflows - making it easy to understand, debug, and maintain complex systems.

Why Use Flows?

🎯 Organization & Clarity

Group related steps together for better code organization and team understanding

👁️ Visual Workflow Management

See your entire workflow in the Motia Workbench - from TypeScript APIs to Python processors to JavaScript analytics

🔍 Enhanced Observability

• Flow-based logging - Filter logs by specific workflows
• Distributed tracing - Follow requests across all steps in a flow
• Real-time monitoring - Watch data flow through your system live

🚀 Team Collaboration

Share visual workflow diagrams with stakeholders, making technical processes accessible to non-technical team members

Creating Multi-Language Flows

Flows are created by tagging your steps with flow names. Each step specifies which flows it belongs to using the flows property in its configuration.

Real-World E-Commerce Flow Example

Here's how to build a complete user onboarding flow using multiple languages:

import { z } from 'zod'
 
export const config = {
  type: 'api',
  name: 'user-registration',
  path: '/users/register',
  method: 'POST',
  
  // Schema validation
  bodySchema: z.object({
    email: z.string().email(),
    name: z.string().min(2),
    password: z.string().min(8)
  }),
  
  emits: ['user.registered'],
  flows: ['user-onboarding'] // 🎯 Flow association
}
 
export const handler = async (req, { emit, logger }) => {
  logger.info('New user registration', { email: req.body.email })
  
  // Create user in database
  const user = await createUser(req.body)
  
  // Trigger Python processing
  await emit({
    topic: 'user.registered',
    data: { user, timestamp: new Date() }
  })
  
  return { status: 201, body: { success: true, userId: user.id } }
}

Flow Best Practices

Visualizing Flows in Motia Workbench

The Motia Workbench is your command center for developing, debugging, and monitoring multi-language workflows in real-time.

Getting Started with Workbench

# In your Motia project directory
npx motia dev

Workbench Features for Multi-Language Workflows

🎨 Language-Coded Visualization

Steps are visually distinguished by language:

• Blue nodes = TypeScript/JavaScript steps
• Green nodes = Python steps
• Custom colors for other languages

⚡ Real-Time Flow Execution

Watch your data flow live across languages:

1. API request hits TypeScript step (blue highlight)
2. Data flows to Python step (green highlight)
3. Results trigger JavaScript step (blue highlight)
4. Complete trace appears in logs panel

🔍 Multi-Language Debugging

• Unified logging - All step logs in one place
• Cross-language tracing - Follow requests across runtimes
• Error highlighting - Instantly spot failing steps
• State inspection - View shared data between steps

📊 Performance Monitoring

• Execution timing - See how long each step takes
• Bottleneck identification - Spot slow steps in your flow
• Resource usage - Monitor memory and CPU per language runtime

Advanced Workbench Usage

Flow Layout Management

The Workbench automatically saves your node positions in motia-workbench.json:

[
  {
    "id": "user-onboarding",
    "config": {
      "steps/01-user-registration.step.ts": {
        "x": -200, "y": 100,
        "sourceHandlePosition": "right"
      },
      "steps/02-enrich-profile.step.py": {
        "x": 100, "y": 100,
        "targetHandlePosition": "left"
      },
      "steps/03-send-welcome.step.js": {
        "x": 400, "y": 100,
        "targetHandlePosition": "left"
      }
    }
  }
]

Team Collaboration

• Commit workbench configs to version control
• Shared layouts - Team sees the same visual organization
• Flow documentation - Visual diagrams serve as living documentation

Real-Time Development Workflow

The Workbench supports hot-reload development across all languages:

1. Edit TypeScript step → Instant reload in browser
2. Modify Python handler → Automatic restart and reconnection
3. Update JavaScript logic → Live updates without losing state
4. Change flow configuration → Visual diagram updates immediately

This enables a seamless multi-language development experience where you can:

• ✅ Write each component in the optimal language
• ✅ See immediate results across the entire workflow
• ✅ Debug issues with full context across languages
• ✅ Monitor performance in real-time

➡️ Learn More about Workbench Features

Ready to build your first REST API? Check out API Endpoints for a complete hands-on tutorial!