SwimFlow Documentation

Quick Start

1. Open the app at /app/.
2. Keep Code tab active and start from Example or a Template.
3. Edit lanes, nodes, and arrows in the editor.
4. Click Render to rebuild diagram from code.
5. Use Save to store a local draft and export when ready.

Interface Overview

The app is split into 3 areas:

• Left code editor, syntax reference, shape palette, properties, lint panel.
• Center diagram canvas with drag/select/connect tools.
• Top command toolbar with primary actions and support actions.

Top Toolbar

Primary row (always visible)

• View tabs: Code, Ref, Shapes, Props, Lint
• Main actions: Render, Save, Sync
• Diagram export: SVG, PNG, Copy PNG
• Search: node id/label input + Go

Support row (mode controlled)

Support actions include Example, Layout, Help, panel toggle, Templates, Snapshots, code import/export, JSON export, and share link.

Mode is persisted in local storage per browser.

Syntax Core

SwimFlow syntax is line-based and human readable.

diagram "Order Flow"
direction LR
theme dark

config {
  laneWidth: 195
  rowHeight: 96
  radius: 8
  fontSize: 10.5
}

lane "Customer" blue
  start s1
  process p1 "Checkout"
endlane

Node Types

Supported node types:

• start, end
• process, decision, note, io, sub
• actor, db, cloud, queue

Node options

Append inline options to any node:

process p2 "Validate" x:120 y:240 w:220 h:70 color:#ff7a5a

Arrows and Ports

Use arrow to connect nodes with style and routing control.

arrow a -> b
arrow a --> b "Async"
arrow d1 -> p2 YES from:right to:left
arrow d1 -> p3 NO style:dashed color:red
arrow x <-> y

Arrow operators

• -> solid
• --> dashed
• -x blocked
• <-> bidirectional

Arrow options

• from: and to: ports
• style: dashed, dotted, thick, double, blocked
• color:, width:, end:, radius:, flip

Code Tools

• Syntax highlighting with autocomplete suggestions.
• Snippet insertion buttons for common commands.
• Live preview render (debounced) + explicit Render.
• Sync to generate code from canvas state.
• Draft autosave + manual Save button.

Lint and Quality

The Lint panel reports structural and quality signals:

• Parser errors
• Duplicate node ids
• Arrows targeting missing nodes
• Lane block mismatch
• Missing start/end nodes
• Isolated nodes and very long labels

Templates and Snapshots

Templates

Use ready-made flows (for example onboarding, incident response, release pipeline) and adapt quickly.

Snapshots

Create named checkpoints of your code locally.

• Save current draft as snapshot
• Load any previous snapshot
• Rename or delete snapshots

Import, Share, Export

Import and code file export

• Import Code accepts plain text or .sf.
• Export Code saves current DSL as .sf.

Share

• Share copies URL with encoded code hash.
• Opening that URL restores the shared code.

Diagram export

• SVG: best for docs and print.
• PNG: best for chat, slides, and quick sharing.
• Copy PNG: sends image directly to clipboard.
• JSON: full project state export (diagram + code + config).

Keyboard Shortcuts

Troubleshooting

Nothing renders

• Confirm at least one lane and one node exist.
• Open Lint panel and resolve parser errors first.

Arrow does not connect as expected

• Verify both node ids exist and are unique.
• Try explicit ports: from:right to:left.
• Use arrow properties to clear waypoints or flip route.

Lost work

• Use Save often and keep snapshots for milestones.
• Draft restore runs automatically on reload in same browser.