Flowline
Try the demo →
Reference

Reference

A glossary, the keyboard shortcuts, where data lives, and fixes for common problems.

Glossary

Term Meaning
Workspace Where a set of projects is stored — this browser, a folder on your computer, a Google Drive folder, or a folder on the server. You pick one on the first screen; everything you do targets the active workspace.
Project A named collection of flows inside a workspace.
Flow One test journey modelled as a graph: an entry point, cards, branches, and ends.
Card A single screen or step. Holds a title, description, inputs, expected results, branches, and an optional background image.
Entry The card a flow starts from, marked ENTRY on the canvas.
Branch An outcome of a card, written as an action and an optional result — e.g. Sign in / Wrong password. Leave the result blank for a plain choice like Back. A branch normally owns one outgoing connection.
Stays on card A branch marked ↩ that records its outcome without moving on — an inline error, a validation message, a toast. It has no connection.
Edge (connection) The line joining a branch to the next card or end, labelled with the branch name.
End A terminal outcome of the flow — e.g. Signed in, Order placed.
Scenario (value set) One concrete run: a pinned path, input values, an expected outcome, and a background override per card.
Background override A scenario setting that replaces a card's default image — how one flow shows Desktop vs. Mobile screens.
Suite An ordered group of scenarios you run together as a regression pass.
Suite run (cycle) One execution of a suite against an environment and build, with a status per scenario.
Pass-rate Passing scenarios ÷ evaluated scenarios (pass + fail) in a cycle. blocked, skipped, retest, and untested are left out of both sides, so the demo's 4 pass / 1 fail / 1 blocked / 1 retest cycle reads 80%, not 57%.
Bug A defect with severity, status, build, and expected-vs-actual, optionally linked to a scenario and run.
Player The full-screen, step-by-step walk of a flow or scenario.
Table The spreadsheet view of a flow. Opens on one scenario's path; Preview shows every card, one column per scenario.
Canvas mode What a drag does on the canvas: Hand pans, Select draws a selection box, Lock protects the layout. Stamp and Connect are tools armed on top of a mode (01).
Note A sticky note on the canvas, for whoever is building the flow. Drag it onto a card to pin it; a pinned note moves and is deleted with that card. Notes travel with exports and appear in no run, table, or report.
MCP server The endpoint that lets an AI assistant drive the tool through its API — hosted at /mcp, or a local stdio process (06). Through a server it reaches Drive and server-folder workspaces; through the flowline-mcp helper it reaches folders on your own computer (09).
Move to durable storage Copying a project out of browser storage into a Drive or server folder, from the Sync panel.
Sync Moving a workspace's changes to and from its backend: Commit saves a revision, Pull brings in others' changes, Push publishes yours (08).
Activity The log of a git workspace's commits, newest first (08).

Views at a glance

View Where Use it to
Workspace picker First screen (/) Create or open a workspace.
Projects After picking a workspace Create, open, or delete projects.
Canvas Editor → Canvas Lay out cards and connections visually.
Table Editor → Table Edit inputs, expected, and scenario values in bulk.
Player Player tab Walk a scenario and file bugs.
Suites Suites tab Manage suites, run cycles, read the dashboard.
Sessions Sessions tab Record an exploratory session across every flow and export it.
Activity Projects screen → History Read a git workspace's commits, newest first (08).

Keyboard shortcuts

Key Where Action
Backspace / Delete Canvas, node or edge selected Delete the selected card or connection.
Enter Any inline field (title, branch label) Commit the edit.
Shift + Enter Multi-line fields Insert a line break instead of committing.
Escape Any inline field Cancel the edit and restore the previous value.
? Canvas Open the help panel listing every canvas mode, tool, and shortcut.

The canvas shortcuts — modes (H, V, L), tools (C, X, Esc), Space to pan, ⌘D to duplicate a selection, ⌘Z / ⌘⇧Z — are listed in that help panel, which the editor generates from the same table it binds its keys from. They are described in Flows and cards.

Deleting a card also removes the connections attached to it. Removing a branch removes the connection that left it. Renaming a branch keeps its connection. Marking a branch stays on card drops its connection, and asks first if it has one.

Where your projects are stored

The server keeps no projects (07). Each workspace kind stores them somewhere else:

Workspace Projects stored in Survives clearing site data Reachable by MCP
This browser The browser's private storage (OPFS) No No
Folder The folder you picked, via the browser Yes Through the flowline-mcp helper, not the server (09)
Drive Your Google Drive folder Yes Yes, once the server is connected to Drive
Local A folder on the server's disk, picked when the workspace is added Yes Yes
Helper A folder on your computer, served by the Flowline helper (09) Yes Through the helper's own MCP server

Local workspaces exist only when LOCAL_WORKSPACES_ENABLED is on — the default when sign-in is off.

Project layout

Whichever kind you use, a project is a directory of plain JSON files — one per card, scenario, suite, note and test record — so two people editing different things never touch the same file, and git diffs show exactly what changed:

<workspace>/
  <project-id>/
    project-meta.json            # name, settings (with the live key)
    templates/<template-id>.json
    sessions/<session-id>/       # session.json, bugs/, results/
    flows/
      <flow-id>/
        flow-meta.json           # name, entry card, owner
        cards/<card-id>.json     # a card and the connections leaving it
        scenarios/<id>.json      # (the type is ValueSet)
        suites/<id>.json
        notes/<id>.json
        asset-meta/<id>.json     # filename and type of an image
        assets/<asset-id>        # the image bytes
        runs/<id>.json
        bugs/<id>.json
        suite-runs/<id>/run.json, results/<id>.json, assignments/<scenario-id>.json
  • settings.liveKey in project-meta.json opens the project's live room (08).
  • A suite result is never edited: recording one adds a file under results/, and a scenario's status is its latest result.
  • People are stored as { "id": "<lowercased email>", "name": "…" }; id is left out when only a name is known, and "agent": true marks what an MCP client wrote (06). The fields are owner on flows, suites and scenarios; tester on runs; reportedBy on bugs and session bugs; startedBy and finishedBy on suite runs; recordedBy on results. A field is left out when Flowline doesn't know who you are. assignee in assignments/<scenario-id>.json is a person too; how an older plain-text file reads: 08. Who can read them: 08.
  • Projects saved by Flowline before this layout (one project.json plus one flow.json per flow) are converted by the first change saved to them, from the editor or an agent. Before converting, every workspace kind except Drive copies the old files to <project-id>/.backup/schema-6/. A Local or Helper folder that is a git repository keeps no copy; recover the old files from git. An older Flowline still writes the old layout (08).
  • Card background images are flow-scoped. Over HTTP they are served at GET /api/projects/<projectId>/flows/<flowId>/assets/<assetId>.
  • On the server, the app's own config lives in ./.data/app. Override with APP_CONFIG_DIR.

Don't point a second server at the default ./.data/app. Running another instance against the same app-config folder can overwrite the workspace registry. Use a different APP_CONFIG_DIR if you need a throwaway instance.

Troubleshooting

The page is blank or won't load. Confirm both processes are up: curl -s -o /dev/null -w "%{http_code}" http://localhost:5174 and the same for http://localhost:8787/api/workspaces should each print 200. If not, restart with npm run dev and watch for API listening on ….

I don't see the Bramble Toys demo project. The demo is bundled with the server and appears automatically in the demo workspace. Restart npm run dev, then reselect the demo workspace in the browser.

My projects vanished. A browser workspace lives in that browser's private storage. Clearing site data, switching browsers, or opening a private window loses it. Nothing is recoverable from the server — it never had a copy. Move projects you care about to Drive or a folder with Move this project to a folder or Drive in the Sync panel.

"Open folder on my computer" is greyed out. The button needs the File System Access API — use Chrome or Edge. Firefox and Safari can still use browser workspaces and Drive.

A card shows no background image. A card falls back to its own default image when the scenario overrides nothing. Open the Table with that scenario picked — or switch to Preview if the card isn't on its path — and check the card's row has an image chosen in the scenario's column, or that the card carries a default in the Inspector's Images section. An agent can set both: add_point_image and set_point_background for the card's own, set_scenario_background for the per-scenario override (06).

My AI assistant (MCP) edits the wrong project, or can't see a workspace. See 06 · MCP → Safety notes.

"This Flowline client is out of date — reload the page, or update flowline-mcp." The server no longer accepts whole-project saves. Reload the web app tab; for an assistant, update flowline-mcp (09).

Port already in use. Another instance is running. Find it with lsof -nP -iTCP:5174 -iTCP:8787 -sTCP:LISTEN and stop it with kill <PID>, or set a different PORT for the API.

Rebuilding this wiki

The pages you are reading are generated from the Markdown chapters in docs/wiki/. After editing a chapter, regenerate the HTML:

npm run build:wiki

Then serve the folder and open it:

cd docs/wiki && python3 -m http.server 4601   # http://localhost:4601