Core Concepts
Five ideas to build your mental model: flows, nodes and handles, categories, the privacy model, the execution model.
A flow is a directed graph of nodes connected by edges. Data moves left to right: input nodes load files, transform and aggregation nodes reshape the data, and output nodes export the result.
A flow has no cycles. Every edge points from a source to a target, and the editor prevents you from creating a loop.
Flows live in your account and persist across sessions. You can rename, share, and delete them from the dashboard.
Nodes and handles
Section titled “Nodes and handles”A node is one step in a flow. Each node wraps a single transform — for example, a CSV Input node, a Filter Rows node, or a Pivot node.
Nodes connect through handles. Every handle has a type: a source handle (right side of the node, output) or a target handle (left side, input). You drag from a source handle to a target handle to create an edge. The editor checks that the schemas at the two ends are compatible — for example, a transform that requires tabular data won’t accept a connection from a node that produces something else.
Most transforms have one input and one output. A few are different:
- Input nodes (CSV Input, JSON Input, XLSX Input) have only a source handle — they read from a file, not from another node.
- Output nodes (CSV Output, JSON Output, XLSX Output) have only a target handle — they write to a file, not to another node.
- Lookup has two target handles: one for the main stream and one for the lookup table.
- Stack Rows accepts two input streams and concatenates them.
The handle definitions live on each TransformDefinition in packages/domain/src/transform-catalog/built-in/ if you want the exact shape for a given transform.
Categories
Section titled “Categories”Every transform belongs to one of four user-facing categories. Each category has a color that shows up as a colored left border on the node and on the matching tab in the transform library.
| Category | Color | What it does |
|---|---|---|
| Input | Blue | Reads data from a file (CSV, JSON, XLSX). |
| Transform | Purple | Reshapes the row stream — filtering, renaming, computing, formatting. |
| Aggregation | Amber | Collapses the row stream — group-by, pivot, unpivot, deduplicate. |
| Output | Green | Writes the result to a downloadable file. |
The category mainly affects browsing — the transform library groups transforms by category, and the canvas color-codes nodes accordingly. It does not affect what a transform can or cannot do.
Privacy model
Section titled “Privacy model”FileBender runs in your browser. Files you drop on an Input node are parsed locally — they don’t get uploaded to a FileBender server. Flows, node configurations, and the data preview live in your browser’s storage (IndexedDB).
There is one transform that breaks this default: Currency Convert fetches live exchange rates from frankfurter.dev. The rates come back as numbers — your row data does not leave the browser — but the network request itself is observable. Currency Convert displays a privacy badge in its node header and on its docs page so you know.
If a future transform sends data externally, it will be marked the same way. The privacyPolicy field on every transform is the source of truth for what crosses the network boundary.
Execution model
Section titled “Execution model”A flow runs as a streaming pipeline. The Input node reads rows and pushes them downstream. Each transform takes rows from its upstream and yields rows to its downstream. The Output node collects rows into a file and offers it for download.
Most transforms are streaming — they process one row at a time and don’t hold the dataset in memory. Filter Rows, Add Column, Rename Columns, Type Coercion are all streaming. They handle very large files comfortably.
Some transforms need the full dataset before they can produce output:
- Sort Rows must see every row before it can decide the order.
- Group By and Pivot must aggregate across the whole dataset.
- Deduplicate must compare every row against every other row.
Full-dataset transforms buffer rows in memory. They work, but they’re more sensitive to large inputs — the Working with Large Files guide walks through how to structure a flow to keep them efficient.
When you change a node’s config, FileBender re-runs the flow from that node downstream. The data preview underneath each node updates as soon as execution finishes.
Where to next
Section titled “Where to next”- The Quick Start Guide walks through a five-step happy path.
- Every transform has its own reference page under Transforms.