# Canvas Basics

> Applies to: ChengOS v0.1.0+ ｜ Last verified: 2026-08-12 ｜ Source: `chengflow-ui/src/features/editor/components`

The editor is a React Flow canvas with a node palette on the left, the graph in the middle,
and a property panel on the right. This page covers moving around and assembling a graph; for
configuring a selected node see [node configuration](/docs/editor-node-configuration).

## Layout

| Region | Contents |
|---|---|
| **Left sidebar** | The node palette, searchable, grouped by category |
| **Canvas** | Your graph, with a minimap and a zoom/fit control |
| **Right sidebar** | The property panel for the current selection |
| **Control panel** | Save, run, and execution status |

## Adding nodes

Drag a node from the palette onto the canvas. Position carries no meaning to the engine —
execution order comes from edges, not from left-to-right placement — but laying a graph out in
reading order makes it dramatically easier to follow, and the editor does not rearrange it for
you.

The palette is the authoritative list of what is installed: it is built from the backend's
node registry, so a newly added node type appears without a frontend release.

## Connecting nodes

Drag from an output port on a node's right edge to an input port on another node's left edge.

**Connections are type-checked.** Each port carries a declared type, and the editor refuses a
pair that cannot carry data safely. A port that will not accept your edge is telling you the
types are incompatible — the check is O(1) against the node registry, so this is instant
rather than a validation pass you trigger later. Fixing it usually means inserting a
`utils/type_cast` node, or choosing a different output port.

An input port generally accepts one edge; output ports can feed many downstream nodes, which
is how you fan a value out to parallel branches.

## Selecting and editing

- **Click** selects a node and opens its properties.
- **Drag a box** on empty canvas selects several nodes; batch operations then apply to all of
  them.
- **Right-click** a node opens a context menu — duplicate, delete, minimize.
- **Minimizing** a node collapses it to a compact card. Purely visual, useful once a graph
  outgrows a screen; a minimized node still shows the fields marked `x-collapsed-visible`.

## Keyboard

| Keys | Action |
|---|---|
| `Ctrl+S` | Save the workflow |
| `Delete` / `Backspace` | Remove the selection |
| Drag on empty canvas | Pan |
| Scroll / pinch | Zoom |

## Notes and organization

The canvas supports free-floating notes, which are annotations rather than graph
participants — they never execute and never carry data. Use them to record why a branch
exists, which is the thing a graph cannot express on its own.

## Saving

Save with the toolbar button or `Ctrl+S`. The first save asks for a name. Workflows persist in
PostgreSQL, not in browser storage, so they are available to every client and to the API
immediately.

Unsaved changes are tracked per tab, and the editor marks a tab dirty rather than
auto-saving — so an experiment you abandon does not overwrite something that worked.

## Importing an existing workflow

Drop a workflow JSON file onto the canvas to import it. This is the same format
`GET /api/v1/workflows/:id/export` produces, which makes export-edit-import a legitimate way
to make bulk mechanical changes that would be tedious by mouse.

## Next steps

- [Node configuration](/docs/editor-node-configuration) — the property panel and schema-driven forms.
- [Testing and debugging](/docs/editor-testing-debug) — run a graph and read what happened.
- [Your first workflow](/docs/quickstart-first-workflow) — a guided build.