# ReactFlowDiagram

Use `ReactFlowDiagram` for architecture graphs, data flow diagrams, dependency maps, command flows, and process flows.

The authoring API is data-only. Do not write React Flow code. The runtime renders with `@xyflow/react`; nodes are draggable and controls/background are included.

## Props

- `title?`: string
- `direction?`: `"LR" | "TB"`, default `"TB"`
  - `"LR"`: left-to-right flow, good for request/command pipelines
  - `"TB"`: top-to-bottom flow, good for layered systems or step sequences
- `groups?`: array of lane/group objects with:
  - `id`: string
  - `label`: string
- `nodes`: array of objects with:
  - `id`: string
  - `label`: string
  - `type?`: `"service" | "data" | "external" | "process"`
  - `group?`: group id string from `groups`
- `edges`: array of objects with:
  - `source`: node id string
  - `target`: node id string
  - `label?`: string

## Left-to-right grouped example

```mdx
<ReactFlowDiagram
  title="Movement command flow"
  direction="LR"
  groups={[
    { id: "ios", label: "iOS" },
    { id: "hub", label: "Hub" },
    { id: "esp", label: "ESP" },
    { id: "external", label: "External clients" }
  ]}
  nodes={[
    { id: "app", label: "Mobile App", type: "external", group: "ios" },
    { id: "api", label: "Command API", type: "service", group: "hub" },
    { id: "queue", label: "Command Queue", type: "data", group: "hub" },
    { id: "firmware", label: "Motor Firmware", type: "process", group: "esp" },
    { id: "observer", label: "Telemetry Client", type: "external", group: "external" }
  ]}
  edges={[
    { source: "app", target: "api", label: "POST /move" },
    { source: "api", target: "queue", label: "enqueue" },
    { source: "queue", target: "firmware", label: "serial command" },
    { source: "firmware", target: "observer", label: "state update" }
  ]}
/>
```

## Simple example

```mdx
<ReactFlowDiagram
  title="Artifact generation flow"
  nodes={[
    { id: "agent", label: "Agent", type: "external" },
    { id: "draft", label: "draft.mdx", type: "data" },
    { id: "compiler", label: "Build Script", type: "process" },
    { id: "html", label: "Standalone HTML", type: "data" }
  ]}
  edges={[
    { source: "agent", target: "draft", label: "writes MDX" },
    { source: "draft", target: "compiler", label: "validated" },
    { source: "compiler", target: "html", label: "compiles" }
  ]}
/>
```

## Rules

- Keep node labels short.
- Edges must reference existing node IDs.
- Use `direction="LR"` for command/request/data flows.
- Use `groups` when lanes such as “iOS”, “Hub”, “ESP”, or “External clients” clarify ownership or boundaries.
- Use diagrams only when relationships or flow matter.