# FlowDrop StateGraph

> Stateful graph execution orchestrator with checkpointing, reducers, loops, and human-in-the-loop support.

## Overview

The `flowdrop_stategraph` module provides an alternative orchestrator that maintains execution state across steps — enabling features like loop iteration, conditional edge evaluation, approval gates, and checkpoint-based resumption.

Unlike the standard runtime orchestrators that process nodes in a single pass, the StateGraph orchestrator maintains a mutable state object that nodes can read and write to. This makes it suitable for complex workflows involving iterative processing, human-in-the-loop approvals, and long-running multi-step operations.

The module includes state management with reducer support, pluggable checkpointers (in-memory for development, entity-based for production), and specialized node processors for loops and approval gates.

## Dependencies

- [flowdrop](flowdrop.md)
- [flowdrop_runtime](flowdrop_runtime.md) (base execution services)
- [flowdrop_workflow](flowdrop_workflow.md) (workflow definitions)
- [flowdrop_pipeline](flowdrop_pipeline.md) (pipeline entities)
- [flowdrop_job](flowdrop_job.md) (job entities)
- [flowdrop_node_type](flowdrop_node_type.md) (node type definitions)
- [flowdrop_node_category](flowdrop_node_category.md) (node categories)

## Configuration

### Admin Pages

| Path | Description |
|------|-------------|
| `/admin/flowdrop/stategraph/test` | Test StateGraph execution form |
| `/admin/flowdrop/stategraph/checkpoints` | List state checkpoints |
| `/admin/flowdrop/stategraph/checkpoint/{id}` | View checkpoint details |

### Permissions

| Permission | Description |
|------------|-------------|
| `administer flowdrop_stategraph` | Full access to StateGraph configuration. Restricted. |
| `view state_checkpoint` | View state checkpoints |
| `create state_checkpoint` | Create state checkpoints |
| `edit state_checkpoint` | Edit state checkpoints |
| `delete state_checkpoint` | Delete state checkpoints |
| `manage approval gates` | Approve or reject approval gate requests |

## Tips and Tricks

### When to Use StateGraph vs Standard Orchestrators

| Use Case | Recommended Orchestrator |
|----------|-------------------------|
| Simple linear workflows | Synchronous (`flowdrop_runtime:synchronous`) |
| Background processing | Asynchronous (`flowdrop_runtime:asynchronous`) |
| Workflows with loops/iteration | **StateGraph** |
| Workflows with approval gates | **StateGraph** |
| Stateful multi-step processing | **StateGraph** |
| Chat-based interactive workflows | **StateGraph** (used by [playground](flowdrop_playground.md)) |

### Checkpointer Selection

- **Memory checkpointer** — Fast, no persistence. Use for development and testing.
- **Entity checkpointer** — Persists checkpoints as Drupal content entities. Use in production for resumable workflows.

### Loop Nodes

The module provides specialized nodes for iteration:

- **ForEachNode** — Iterates over an array, executing downstream nodes for each item
- **IteratorStartNode** — Initializes an iterator
- **IteratorNextNode** — Advances to the next item
- **IteratorCollectNode** — Collects all iterator results into an array
- **LoopControlNode** — Controls loop behavior (break, continue)

### Approval Gates

The `ApprovalGateNode` pauses workflow execution at designated points, waiting for human approval before continuing. This integrates with the [flowdrop_interrupt](flowdrop_interrupt.md) module for the actual pause/resume mechanics.

## Developer API

### Services

| Service ID | Class | Description |
|-----------|-------|-------------|
| `flowdrop_stategraph.orchestrator` | `StateGraphOrchestrator` | Main orchestrator service |
| `flowdrop_stategraph.state_manager` | `StateManager` | State lifecycle, reducer application, serialization |
| `flowdrop_stategraph.checkpointer_factory` | `CheckpointerFactory` | Creates the appropriate checkpointer |
| `flowdrop_stategraph.memory_checkpointer` | `MemoryCheckpointer` | In-memory checkpointing |
| `flowdrop_stategraph.entity_checkpointer` | `EntityCheckpointer` | Entity-based persistent checkpointing |
| `flowdrop_stategraph.conditional_edge_evaluator` | `ConditionalEdgeEvaluator` | Evaluates state conditions for routing |
| `flowdrop_stategraph.array_iterator_helper` | `ArrayIteratorHelper` | Array iteration with state management |
| `flowdrop_stategraph.approval_gate_handler` | `ApprovalGateHandler` | Manages pause/resume for approval workflows |

### Entities

#### FlowDropStateCheckpoint (Content Entity)

Stores serialized state checkpoints for resumable execution.

### Node Processors

| Plugin | Description |
|--------|-------------|
| `ApprovalGateNode` | Pauses execution for human approval |
| `LoopControlNode` | Controls loop behavior (break, continue) |
| `ForEachNode` | Iterates over arrays |
| `IteratorStartNode` | Initializes an iterator |
| `IteratorNextNode` | Advances to next item |
| `IteratorCollectNode` | Collects iterator results |
| `StateStorageNode` | Reads/writes to the state store |

### StateAwareProcessorInterface

Node processors that need access to the execution state can implement `StateAwareProcessorInterface` to receive the current state and participate in state management.

## References

- [flowdrop_runtime](flowdrop_runtime.md) — base execution engine
- [flowdrop_orchestration](flowdrop_orchestration.md) — orchestrator plugin system
- [flowdrop_interrupt](flowdrop_interrupt.md) — interrupt mechanics for approval gates
- [flowdrop_playground](flowdrop_playground.md) — interactive testing (uses StateGraph)
- [Workflow Snapshots and Orchestrators](../development/workflow-snapshots-and-orchestrators.md)
