Core Concepts
Understand the building blocks of FlowTrux: organizations, workspaces, workflows, nodes, and roles.
Organizations
An Organization is the top-level tenant in FlowTrux. Every resource - workspaces, workflows, AI providers, MCP servers - belongs to an organization.
Each user belongs to one organization. The organization's capabilities depend on the subscription plan - from Free (basic usage) to Enterprise (full team collaboration). Paid plans require a billing address; business entities can provide a Tax ID.
Organization
├── Workspaces
│ ├── Workflows
│ └── Global Contexts
├── AI Provider Keys
├── MCP Server Configs
├── Members (with roles)
└── Invite Links
Workspaces
A Workspace is a logical grouping within an organization that provides resource isolation. Workflows live inside workspaces, and you can control which AI providers and MCP servers are available in each workspace.
Use workspaces to separate concerns - for example, a "Production" workspace and a "Development" workspace, or per-team workspaces in a larger organization.
Key properties:
- Name and description for identification
- Assigned AI providers - which API keys are available to workflows in this workspace
- Assigned MCP servers - which tool servers are available
- Member permissions - what MEMBER-role users can do (edit, delete, execute workflows)
Workflows
A Workflow is a directed graph of nodes and edges that defines an automation. Workflows are stored as JSON containing the node definitions, their configurations, and the connections between them.
Workflows belong to a workspace and are executed by the FlowRunner engine, which traverses nodes in BFS (breadth-first) order.
Nodes
FlowTrux has five node types, each with a distinct color:
| Node | Color | Purpose |
|---|---|---|
| Trigger | Emerald (green) | Entry point - starts workflow execution via manual run, webhook, or cron schedule |
| Agent | Violet (purple) | AI/LLM node - sends prompts to Claude or GPT models, optionally with MCP tools |
| Action | Blue | Performs operations - HTTP requests, MCP tool calls, data transforms, delays |
| Logic | Amber (yellow) | Controls flow - if-else conditions, switch statements, loops, parallel branches |
| Aggregator | Cyan (teal) | Combines outputs from parallel branches - merge, concat, filter, reduce |
Each node produces output that downstream nodes can reference using template variables:
{{steps.agent-1.output.response}}
{{steps.action-2.output.data.items}}
{{trigger.data.webhookPayload}}
Execution
When a workflow runs, the engine:
- Starts at the Trigger node
- Traverses connected nodes in BFS order
- Resolves template variables from previous node outputs
- Executes each node (API calls, LLM requests, evaluations)
- Stores results in the execution context under
steps.<nodeId>.output - Records execution history with per-node logs, timing, and status
Executions can be streaming (SSE for real-time updates) or synchronous (wait for completion). Webhook triggers support fire-and-forget mode for background execution.
Template Variables
Data flows between nodes through Handlebars-style template variables:
| Variable | Description |
|---|---|
{{steps.nodeId.output.field}} | Output from a previous node |
{{trigger.data}} | Data from the trigger (webhook body, static data) |
{{trigger.data._query}} | URL query parameters (webhook triggers) |
{{global.key}} | Global context key-value store (workspace-scoped) |
{{item}} | Current element inside a loop |
{{index}} | Current iteration index inside a loop (0-based) |
When a template is the entire value (e.g., "{{steps.x.output.array}}"), the original type is preserved - arrays stay arrays, objects stay objects. When embedded in a string (e.g., "Count: {{output.count}}"), the result is string interpolation.
Roles and Permissions
FlowTrux uses role-based access control at the organization level:
| Role | Access |
|---|---|
| Owner | Full access to everything. Manage organization settings, members, workspaces, AI providers, MCP servers. Can delete organization. |
| Member | Can only access workspaces they are explicitly added to. Cannot see Settings. Workflow actions are governed by per-workspace permissions. |
Member Permissions
For MEMBER-role users, workflow permissions are configured per workspace:
| Permission | What It Controls | Default |
|---|---|---|
canEdit | Create, edit, copy, import/export workflows | Off |
canDelete | Delete workflows | Off |
canExecute | Run workflows | Off |
The Owner always has full permissions in all workspaces.
Invite Flow
Adding new members to an organization:
- Owner creates an invite link in Settings > Members
- New user visits the invite URL
- User registers with name, email, and password
- A membership request is created (status: PENDING)
- Owner approves the request in Settings > Members > Pending Requests
- On approval, the user becomes a Member in the organization
Next Steps
- Editor Basics - learn how to use the visual workflow editor
- Quickstart - build your first workflow