Flow Basics

Flows are the core concept in TinySystems. A flow defines an automation by connecting components together to process data.

What is a Flow?

A flow is a visual representation of an automation workflow. It consists of:

• Nodes: Instances of components that perform specific tasks
• Edges: Connections between nodes that define data flow
• Configuration: Settings for each node and edge

┌──────────┐     ┌──────────┐     ┌──────────┐
│  Trigger │────▶│ Process  │────▶│  Output  │
│  (HTTP)  │     │ (Modify) │     │ (Notify) │
└──────────┘     └──────────┘     └──────────┘

Flow Lifecycle

Flows progress through distinct states:

┌─────────┐     ┌──────────┐     ┌─────────┐
│  Draft  │────▶│ Deployed │────▶│ Running │
└─────────┘     └──────────┘     └─────────┘
     │               │                │
     └──────◀────────┴────────◀───────┘
              (Edit/Redeploy)

States

State	Description
Draft	Flow is being edited, not active
Deploying	Being deployed to cluster
Deployed	Active on cluster, ready to execute
Running	Currently processing messages
Error	Deployment or runtime error

Transitions

• Save: Draft changes are saved
• Deploy: Flow is pushed to the cluster
• Trigger: Execution begins (external event or manual)
• Complete: Execution finishes
• Undeploy: Flow is removed from cluster

Creating Flows

New Flow

1. Navigate to your project
2. Click New Flow
3. Enter a descriptive name
4. Click Create

Naming Conventions

Good flow names:

• Describe the purpose: "Process Customer Orders"
• Indicate the trigger: "Webhook - Slack Notifications"
• Include environment hints: "[DEV] Data Sync"

Flow Settings

Access via the gear icon in the toolbar:

Setting	Description	Default
Name	Display name	(required)
Description	Purpose documentation	(optional)
Tags	Organization labels	(optional)
Timeout	Max execution time	5 minutes
Retry Policy	Error retry behavior	No retry

Flow Structure

Entry Points

Every flow needs at least one entry point:

Component	Trigger Type
HTTP Server	Incoming HTTP request
Ticker	Time-based schedule
Signal	Manual trigger
Queue Consumer	Message queue

Processing Nodes

Transform and route data:

Component	Purpose
Modify	Transform data structure
Router	Conditional branching
Split	Iterate over arrays
Async	Non-blocking execution

Exit Points

Complete the flow:

Component	Purpose
HTTP Server (response)	Send HTTP response
HTTP Client	Call external API
Debug	Log output
(End of chain)	Flow completes

Execution Model

Message-Based

Flows execute based on messages flowing between nodes:

Message arrives at Node A
    │
    ▼
Node A processes message
    │
    ▼
Node A emits output message
    │
    ▼
Edge transforms data (expressions)
    │
    ▼
Message arrives at Node B
    │
    ...continues...

Blocking Execution

By default, execution is blocking:

• Each node waits for downstream nodes to complete
• Backpressure is automatic
• Errors propagate back to the source

Node A ──▶ Node B ──▶ Node C
   │          │          │
   │    waits for   waits for
   │     Node B      Node C
   │          │          │
   ▼          ▼          ▼
Complete ◀── Complete ◀── Complete

Parallel Execution

For parallel processing, use the Async component:

         ┌──▶ Branch 1 ──┐
Input ──▶│               ├──▶ Output
         └──▶ Branch 2 ──┘

Or connect multiple outputs:

          ┌──▶ Notify Slack
Input ────┤
          └──▶ Notify Email

Working with Multiple Flows

Flow Organization

Organize flows within projects:

Project: E-commerce
├── Flows
│   ├── Order Processing
│   ├── Inventory Sync
│   ├── Customer Notifications
│   └── Analytics Pipeline

Flow Communication

Flows can communicate:

1. Shared endpoints: One flow triggers another via HTTP
2. Shared nodes: Same underlying component instance
3. Events: Publish/subscribe patterns

Flow Dependencies

Document dependencies:

• External services called
• Database connections
• Other flows triggered

Best Practices

1. Keep Flows Focused

Each flow should do one thing well:

❌ Avoid: "Handle Everything Flow"
✅ Better: "Process Orders Flow" + "Send Notifications Flow"

2. Use Descriptive Names

For both flows and nodes:

❌ Avoid: "Flow1", "Modify", "Router"
✅ Better: "Order Validation", "Extract Customer", "Route by Status"

3. Handle Errors

Always consider error cases:

┌──────────┐     ┌──────────┐
│ Process  │────▶│ Success  │
│          │     │ Handler  │
└──────────┘     └──────────┘
      │
      └──▶ Error Handler

4. Add Documentation

Use flow descriptions and node names to document:

• Purpose of the flow
• Expected inputs
• Side effects
• Dependencies

5. Version Control

Track flow changes:

• Use flow revisions
• Review before deploying
• Roll back if needed

Flow Templates

Common flow patterns:

Request-Response

HTTP Server ──▶ Process ──▶ HTTP Server (response)

Scheduled Task

Ticker ──▶ Fetch Data ──▶ Process ──▶ Store

Event Handler

Webhook ──▶ Validate ──▶ Router ──┬▶ Handle A
                                  └▶ Handle B

Data Pipeline

Source ──▶ Transform ──▶ Filter ──▶ Destination

Next Steps

• Nodes and Edges - Deep dive into connections
• Data Mapping - Transform data between nodes
• Flow Revisions - Version control for flows