# Flow designer

The flow designer is a visual graph editor for composing decision logic. Open it from **Flows** → select a flow.

## Canvas basics

| Action | How |
|--------|-----|
| Pan | Drag background |
| Zoom | Scroll wheel or controls |
| Add node | Drag from palette onto canvas |
| Connect | Drag from node handle to another node |
| Select | Click node or edge |
| Configure | Inspector panel on the side |
| Delete | Select + Delete key |

Node **position** is saved in the graph JSON — reopening the designer preserves layout.

## Palette

| Node | Purpose |
|------|---------|
| Start | Entry point; input schema + response type |
| HTTP | Call an API source operation |
| Condition | If/else branch (JSONata) |
| Transform | Compute and store a value |
| Wait for event | Pause until resume |
| Decision | Set response fields |
| End | Finish and return |

→ Field-level detail: [Node types](flow-nodes.md)

## Inspector panel

Selecting a node opens the inspector:

- **Label / description** — documentation for humans and agents
- **Type-specific fields** — operation id, expressions, timeouts
- **Expression editor** — Monaco with JSONata syntax and intellisense

Expressions see `input` and `nodes.{id}` from prior steps.

→ [JSONata expressions](expressions-jsonata.md)

## Wiring conditions

A condition node needs **two outgoing edges**:

```
condition_1 ──when: "true"──► path_a
            └──when: "false"──► path_b
```

Other node types use a single default edge (omit `when`).

## HTTP nodes

1. Ensure an [API source](api-sources.md) exists
2. Add HTTP node → pick source + operation
3. Map inputs: parameter name → JSONata expression

Example mapping:

| Parameter | Expression |
|-----------|------------|
| `userId` | `input.userId` |
| `status` | `"active"` |

Response available as `nodes.{nodeId}.body` in downstream expressions.

## Decision + end pattern

Modern flows use a **response type** on the start node:

```
start → … → decision (sets responseValues) → end
```

Each decision merges keys into the accumulator. The end node validates and returns.

Legacy flows without a response type may use `decision.result` as the final payload — migrate to response types for clearer contracts.

## Input schema (start node)

Declare what callers send to `/v1/evaluate`:

| Field | Type | Required |
|-------|------|----------|
| `userId` | string | yes |
| `amount` | number | yes |

Drives runtime validation and expression intellisense.

## Save, publish, sync

| Action | Effect |
|--------|--------|
| **Save draft** | Updates server draft; visible to CLI on next pull |
| **Publish** (console) | Creates callable version for evaluate API |
| **fcc pull** | Copies draft JSON to `.fetchcatch/flows/` |
| **fcc apply** | Pushes local JSON to server draft |
| **fcc publish** | Snapshots draft as callable version (CLI path) |

Editing the same flow in console and git without syncing causes conflicts — pull before apply.

## Validation

The designer validates before save:

- Missing start node
- Duplicate node ids
- HTTP node without operation
- Condition without expression or branches
- Unreachable nodes

Fix errors listed in the validation panel before publishing.

## Testing

1. **Dry run** via evaluate with `"dryRun": true` where supported
2. **Runs tab** — inspect a live execution step-by-step
3. **Fixture input** — use the evaluate panel in console (if available) or curl

→ [Runs & debugging](runs.md)

## Related

- [Flow JSON schema](flow-graph-schema.md) — on-disk format
- [Core concepts](concepts.md)
- [Getting started](getting-started.md)