# Flow Studio Specification

## Core Concepts

### Node

- `id` (string, unique)
- `label` (display name)
- `type` (e.g., `event`, `function`, `output`, `subflow`)
- `style` (string, optional Mermaid style snippet)
- `metadata` (internal dict; currently populated from `style`)

### Edge

- `source` (node id)
- `target` (node id)
- `label` (optional edge label)
- `style` (optional Mermaid link style snippet)
- `metadata` (internal dict; currently populated from `style`)

### FlowGraph

- `nodes: List[Node]`
- `edges: List[Edge]`

---

## Execution

- Start nodes are those with **no incoming edges**.
- The simulator performs a **depth-first traversal** from each start node.
- For each visited node, it appends a log line describing:
  - Node id, type, and label.

No real code is executed yet — this is an execution **preview** engine.

---

## UI Mapping

- **Nodes table** → Gradio Dataframe:
  - Columns: `id`, `label`, `type`, `style`.
- **Edges table** → Gradio Dataframe:
  - Columns: `source`, `target`, `label`, `style`.
- **Diagram**:
  - Mermaid diagram rendered as a Markdown code block.
  - Node `style` fields become `style <id> <style>` lines.
  - Edge `style` fields become `linkStyle <index> <style>` lines.
- **Simulation**:
  - Markdown log of execution order.

---

## Flow Command DSL

A small SQL-like language is used to manipulate the graph:

- Add / upsert a node

  ```text
  ADD NODE id=event_in label="Incoming Event" type=event