docs/FLOW_STUDIO_SPEC.md

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

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