Docs
Documentation
Learn how to build, run, and review your Python workflows step by step.
Introduction
FlowCraft lets you build, run, and review workflows as visual flowcharts. You place nodes on a canvas, connect them with links, and run the flow step by step. Python scripts live in your project's Scripts folder; each Python node on the canvas points to one of those scripts.
When you run a flowchart, FlowCraft tracks what happened — which nodes ran, what they returned, and any data you chose to save. You can review that history on the Dashboard and in Matrix.
Getting around
Use the left sidebar to switch pages. The flowchart you are working on stays selected as you move between Build, Scripts, Run, Matrix, and other pages.
Dashboard
The dashboard is your at-a-glance view of one flowchart. Use it to see how often you run it, whether runs are succeeding, and what happened recently.
What you will see
At the top, quick stats summarise your flowchart:
- how many times it has been run
- average success rate and run time
- how many data save nodes you have
- Python nodes that do not have a script assigned yet
- nodes that are not connected to anything (orphaned)
Below that, recent executions lists your latest runs with status, how many nodes ran, progress, and how long each run took. Use the actions column to open a full report for any run.
The execution history chart shows progress across recent runs so you can spot trends quickly.
Build
Your first flowchart
A typical workflow looks like this:
- Add nodes of any type.
- Shift + drag from one node to another to create links (execution order).
- Select each Python node and assign a script from your Scripts folder in the properties panel on the right.
- Wire arguments so data from earlier nodes feeds into later ones.
- Switch to Run and press Start.
The canvas
- Drag nodes, groups, and labels to arrange them.
- Pan and zoom to navigate large flowcharts.
- Right-click for actions like delete or duplicate.
- Shift + drag between two nodes to connect them with a link.
Toolbar on the left
| Button | What it does |
|---|---|
| Group select | Drag a rectangle to select multiple items |
| Deselect | Clear the current selection |
| Reset view | Centre the canvas on the first node |
| Undo / Redo | Reverse or repeat recent edits |
| Auto track | During a run, keep the active node in view |
| Error circles | Highlight nodes that had errors |
| Flow circles | Show execution-order hints on nodes |
Adding nodes
The annotation toolbar adds text labels and arrows for notes on the canvas. They do not run — they are only for documentation.
Properties panel
Click any node, link, group, or annotation to open the properties panel on the right. What you see depends on what you selected.
Most selections include a delete button in the panel header. Some node types can be renamed from the panel as well.
Selecting multiple items
When you select more than one node, link, or annotation at once, the properties panel switches to multi-select mode.
How to select multiple items
- Use group select on the left toolbar and drag a rectangle.
- Or shift-click individual items.
Multi-select properties panel
| Panel | What you use it for |
|---|---|
| Create group | Turn the current selection into a group |
| Delete | Remove everything you selected |
Multi-select is a temporary state — it is not a node that stays on your flowchart.
Python node
The Python node is the heart of most flowcharts. Each one runs a single Python script from your Scripts folder.
Add a Python node
Click Python on the build toolbar, or drag it onto the canvas.
Assign a script
- Select the node.
- In the properties panel, open python file and pick an existing script or create a new one.
- The panel shows whether the file is found, missing, or no longer exists.
Properties panel
| Panel | What you use it for |
|---|---|
| Description | Notes about what this step does (optional) |
| Python file | Choose or create the script to run |
| File location | See the path of the assigned script |
| Execute through node | Turn off to stop the run at this node instead of continuing |
| Ignore node | Skip this node entirely during runs |
| Quick actions | Open the script in your editor, test this node alone, copy the file path |
| Arguments (data in) | Map values from earlier nodes into this script's inputs |
| Returns (data out) | See what this script returns to downstream nodes |
| Downstream flow order | When several links leave this node, set which branch runs first |
Input prompts
If your script uses Python's input() function, FlowCraft may add a small input node beside it automatically. Type test values there so runs do not wait for keyboard input.
When you run
During a full flow run, the script runs as a normal Python file. When you test a single node, FlowCraft calls the main function in the script with the arguments you configured.
Input node
An input node supplies test values when a Python script asks for keyboard input with input().
You do not add these from the toolbar — FlowCraft creates one automatically when you assign a script that uses input().
How to use it
Type values in the input fields on the canvas next to the Python node, or set them when you run. The input node itself does not run as a separate step; it only feeds values into its linked Python node.
IF Splitter
An IF splitter splits your flow into branches. Only the branch whose condition is true will run.
Add an IF splitter
Click IF Splitter on the build toolbar, or drag it onto the canvas.
Connect branches
Shift + drag from the splitter to each possible next node. Each outgoing link can have its own conditions — see IF condition below.
Properties panel
| Panel | What you use it for |
|---|---|
| Available variables | See which values from earlier nodes you can use when writing conditions on the outgoing links |
When you run
At the splitter, FlowCraft checks each branch's conditions and follows only the path that matches.
IF condition
An IF condition is not a separate node on the canvas — it is the condition box on a link coming out of an IF splitter.
Set up a condition
- Connect the splitter to the next node with shift + drag.
- Select the link or the condition box on the link.
- Use the condition builder in the properties panel to define when this branch should run.
Properties panel (Build)
| Panel | What you use it for |
|---|---|
| Description | Notes about this branch |
| Condition builder | Pick a variable, choose an operator (equals, greater than, etc.), and set a value or compare to another variable |
| Active conditions | Review, reorder, combine with AND/OR, or remove conditions you have already added |
Properties panel (Run)
| Panel | What you use it for |
|---|---|
| Active conditions | See which rules apply to this branch |
| IF result | See whether this branch was taken in the current or last run |
Data save node
A data save node stores one variable from a Python node's output so you can review it later in Matrix and the execution view.
Add a data save node
Data save nodes usually appear when you save a variable from a Python node's run panel, or when FlowCraft links one magnetically to a Python node on the canvas.
Properties panel (Build)
| Panel | What you use it for |
|---|---|
| Description | Note what this saved value represents |
| Source variable | See which return value from the linked Python node will be stored |
Properties panel (Run)
| Panel | What you use it for |
|---|---|
| Save variable | Choose or confirm which variable to save when the linked node finishes |
When you run
After the linked Python node completes successfully, FlowCraft stores the chosen variable under that run's history.
Database interaction node
A database interaction node reads or writes rows in your FlowCraft Database tables during a run.
Add a database interaction node
Click Database Interaction on the build toolbar, or drag it onto the canvas.
Create and edit tables on the Database page before you reference them here.
Properties panel
| Panel | What you use it for |
|---|---|
| Description | Notes about this database step |
| Interaction builder | Set up a read or write: choose table, column, how to find the row, and which variable supplies or receives the value |
| Active interactions | Manage the list of interactions on this node — enable, edit, or remove them |
When you run
When execution reaches this node, FlowCraft performs the configured read or write against your database.
API node
An API node calls an external service — for example Google Sheets — as part of your flow.
Add an API node
Click API on the build toolbar, or drag it onto the canvas.
Connect the service first
Go to Settings → Connected APIs and sign in to the service you need before the node can run successfully.
Properties panel
| Panel | What you use it for |
|---|---|
| API | Choose which connected service this node uses |
| Authentication | Check whether you are signed in; link to connect if not |
| API blocks | Configure the specific actions this node performs (steps vary by service) |
When you run
When execution reaches this node, FlowCraft runs the API actions you configured.
Cloud save node
A cloud save node is for saving data to a cloud destination as part of a flow.
Add a cloud save node
Click Cloud Save on the build toolbar, or drag it onto the canvas.
Configuration options for this node type are still expanding. Check the properties panel and Settings for the latest options available in your version.
AI node
An AI node runs an AI or language-model step in your flow.
Add an AI node
Click AI on the build toolbar, or drag it onto the canvas.
Model and prompt settings may be available in Settings depending on your setup. Select the node on the canvas to see what you can configure in the properties panel.
When you run
When execution reaches this node, FlowCraft runs the AI step you configured.
Links
Links are the lines between nodes. They tell FlowCraft which step runs next.
Create a link
Hold Shift and drag from one node to another.
Properties panel (Build)
| Panel | What you use it for |
|---|---|
| Link to / from | See which nodes this connection joins |
| Execute through link | Turn off to stop the run before it follows this link |
| Needed variables | See what data the target node expects from this connection |
Properties panel (Run)
| Panel | What you use it for |
|---|---|
| Link to / from | Confirm which nodes are connected |
| Execute through link | Same stop-here control during a run |
Links from an IF splitter can also carry IF conditions — select the link to edit them.
Groups
A group is a coloured box around several nodes. Groups help you organise the canvas; they do not change how the flow runs.
Create a group
- Click group select on the left toolbar and drag a rectangle over the nodes you want.
- In the properties panel, choose create group from selection.
You can also group nodes from the right-click menu when several items are selected.
Properties panel
| Panel | What you use it for |
|---|---|
| Change colour | Set the group's background colour |
| Group actions | Ungroup, rename, or other group-level actions |
| Nodes in group | See everything inside the group |
To remove a group without deleting the nodes, use ungroup in group actions.
Annotations
Annotations are labels and arrows on the canvas. They never run — use them to document your flowchart for yourself or your team.
Text annotation
Click Text on the annotation toolbar, or drag it onto the canvas. Double-click or select it to edit.
| Panel | What you use it for |
|---|---|
| Font size | Make the label larger or smaller |
| Change colour | Set text or background colour |
Arrow annotation
Click Arrow on the annotation toolbar, or drag it onto the canvas.
| Panel | What you use it for |
|---|---|
| Change colour | Set the arrow colour |
Scripts
This page is your file manager for Python and other project files. Everything here is what your flowchart nodes can run.
Browse folders and files
The main list shows files and folders in your project. Click a folder to open it. Use the breadcrumb at the top or the up button to go back.
Create a new file or folder
Use new file or new folder in the toolbar. New Python files can be linked to nodes on the Build page.
Move or delete
Select one or more items, then move or delete them. Deleting removes files from your project — only do this if you are sure the flowchart no longer needs them.
Open in your editor
If you have set a default editor in Settings, you can open any script directly in Cursor, VS Code, or another editor from this page.
Preview a file
Hover over a file to preview it, or pin the preview to keep it open. Text, images, and PDFs are supported so you can check a file without leaving FlowCraft.
Run
Start a run
- Open the flowchart you want to run (use the selector at the top of the sidebar if needed).
- Click Run in the sidebar.
- Press Start on the canvas.
FlowCraft runs your nodes in order, following the links you drew in Build. A live run feed at the bottom of the screen shows each step as it happens.
While a run is in progress
- The sidebar navigation is locked so you do not accidentally leave mid-run.
- Select a node to see its execution status, console output, return values, and any files created.
- Use Clear to reset run visuals on the canvas when you want a clean view.
How execution works
- Nodes run in the order defined by your links.
- At an IF splitter, only the branch whose condition is true continues.
- A Python node runs its linked script. If you marked a node to ignore, it is skipped.
- Stop here on a node or link stops the run at that point — useful for testing one section of a large flow.
- Data save nodes store a variable when their linked Python node finishes.
Test a single node
From Build, you can also run one Python node on its own (via quick actions in the properties panel). That is helpful when you are still writing the script and do not want to run the whole flow.
Multirun
Set up a multirun
- Click multirun in the sidebar.
- In the Multiruns panel on the left, click + to create a new multirun definition.
- In the Executions table at the top, add rows. Each row is one separate run with its own input values.
Add rows manually or from a CSV
- Click add to create a row and fill in values by hand.
- Click Upload CSV to import many rows at once. Column headers in the CSV should match the input names your flowchart expects.
Run the batch
Press Start in the controls bar at the bottom. FlowCraft runs each row in sequence. You can Pause, Stop, or Skip while a batch is running.
Use Clear to reset run visuals on the canvas after a batch finishes.
Review results
Multirun results appear on the Matrix page under multirun tabs, alongside your normal single runs.
Matrix
Matrix is where you browse saved data from your runs. If you use data save nodes in your flowchart, the variables they capture show up here as columns you can compare across executions.
Switch between runs
Use the tabs at the top to move between individual executions or multirun batches for the current flowchart. In-progress runs update automatically when they finish.
Read the grid
Each column usually represents a saved variable from a data save node. Each row or block represents an execution. Click a cell to preview a value; open it fully if you need more detail.
Delete old runs
You can delete single executions or batches from Matrix when you no longer need the history. You will be asked to confirm before anything is removed.
Execution view
When you open a specific run (from Matrix, the Dashboard, or elsewhere), you get a full execution view:
- overall status — success, error, or cancelled
- how long the run took and how many nodes ran
- a variables table listing everything saved or returned
- files created during the run, grouped by which node wrote them
Click any variable or file to inspect it in more detail.
Variable viewer
The variable viewer opens when you click a saved variable, a file from a run, or when you preview a script from Scripts.
It shows the full value in a readable format — text, JSON, images, PDFs, and other types are formatted so you can actually read them. You can copy or download where the app supports it.
Database
FlowCraft includes a built-in database for storing tables of data your workflows can read and write. Database interaction nodes on the canvas use these tables at run time.
Pick a table
Use the dropdown at the top to choose a table. The grid shows its rows and columns.
View and edit data
Click any cell to open the detail panel on the right. You can inspect the value, see basic stats, copy content, and switch to edit mode to change a value and save it back.
Create or change table structure
Create new tables when your workflow needs a place to store data. You can add, remove, or rename columns and set column types (numbers, text, and so on).
Back up your database
Use import and export to back up the database file or move it to another machine.
Transfer
Use Transfer to pack up a flowchart and everything tied to it, or to restore a pack you exported earlier.
Export
Choose what to include in the export:
- the flowchart itself (always included)
- run history and files created during runs
- backups
- multirun definitions
Scripts linked to your nodes are included when you export. You need a flowchart selected — export is disabled if none is chosen.
Import
Upload a previously exported archive. FlowCraft shows whether the import succeeded and which flowchart was restored.
When to use this
- moving a project to a new computer
- sharing a flowchart with someone else
- making a safety backup before big changes
Visualisers
Visualisers let you build custom HTML, CSS, and JavaScript views of your data — charts, layouts, or any visual you write yourself — fed by saved variables or execution results.
Choose your data
In the sidebar, pick which execution or saved variable should feed the visualiser. Match and value columns map rows from Matrix or database data into what your visual code receives.
Write the visual
Edit HTML, CSS, and JavaScript in the source panels. Your code runs inside a preview iframe so you can see the result immediately.
You can describe what you want broadly — FlowCraft includes clear instructions for AI code models to generate the visualiser.
Preview and debug
The main preview area shows the visual with live data. The console panel shows output from the preview, which helps when something does not render as expected.
Quick view
Use quick view actions to snapshot or copy matched data rows while you are tuning selectors or layouts.
Settings
Settings control how FlowCraft behaves for your project and the current flowchart.
Project settings
- project root — where FlowCraft looks for files and data
- default editor — which app opens when you click "open in editor" on Scripts
- execution timeout — how long a node can run before FlowCraft stops it
- rename flowchart, clear history, and delete flowchart for the selected chart
Backups
View automatic backups of your flowchart, restore an older version, or delete backups you no longer need.
Mermaid
Generate a diagram image of your flowchart for documentation or sharing. Filter which node types appear in the export.
Mermaid diagrams provide useful context for AI models helping you understand or modify your project.
Sidebar and status bar
Customise which panels appear in the properties sidebar when you select a node, and which info appears in the status bar on each page.
Modules
Manage the Python environment FlowCraft uses — install packages your scripts need, search installed modules, and review what is available.
Connected APIs
Sign in to external services (such as Google Sheets) so API nodes in your flowchart can use them.