# FlowDrop Orchestration

> Orchestrator plugin system, contracts, and helper services that define how workflows are executed.

## Overview

The `flowdrop_orchestration` module provides the plugin system and contracts for workflow orchestrators. An orchestrator is responsible for the actual execution strategy — deciding how nodes are scheduled, whether execution is synchronous or asynchronous, and how errors are handled.

This module does not provide any concrete orchestrators itself. Instead, it defines the `OrchestratorPluginInterface`, the plugin discovery mechanism (via PHP 8 attributes), and a helper service for resolving which orchestrator to use. Concrete orchestrators are provided by [flowdrop_runtime](flowdrop_runtime.md) and [flowdrop_stategraph](flowdrop_stategraph.md).

## Dependencies

- [flowdrop](flowdrop.md)

## Configuration

### Orchestrator Selection

Orchestrators are selected at execution time based on configuration. The `OrchestratorHelper` service resolves the appropriate orchestrator with fallback handling. Modules like [flowdrop_trigger](flowdrop_trigger.md) allow per-trigger orchestrator configuration.

## Tips and Tricks

### Available Orchestrators

Once the relevant modules are enabled, these orchestrators are available:

| Plugin ID | Module | Description |
|-----------|--------|-------------|
| `flowdrop_runtime:synchronous` | [flowdrop_runtime](flowdrop_runtime.md) | Direct execution with immediate results |
| `flowdrop_runtime:synchronous_pipeline` | [flowdrop_runtime](flowdrop_runtime.md) | Pipeline-based synchronous execution |
| `flowdrop_runtime:asynchronous` | [flowdrop_runtime](flowdrop_runtime.md) | Queue-based background execution |
| `flowdrop_stategraph:stategraph` | [flowdrop_stategraph](flowdrop_stategraph.md) | Stateful graph execution with checkpointing |

### Orchestrator Capabilities

Each orchestrator declares its capabilities, which allows the system to match the right orchestrator to the task:

- `synchronous_execution` — Can execute inline during a request
- `async_execution` — Can execute in the background via queues
- `parallel_execution` — Can run independent nodes concurrently
- `retry_support` — Can retry failed nodes
- `error_recovery` — Can recover from partial failures
- `pipeline_based` — Uses pipeline/job entity tracking
- `job_tracking` — Provides per-node execution tracking
- `stateful` — Maintains execution state across steps
- `checkpointing` — Can save and restore execution state
- `interrupt_support` — Can pause for human-in-loop input

## Developer API

Starting with 1.0.0-beta1, the **Orchestrator plugin contracts** are part of the stable public API (`@api`):

- `Orchestrator` attribute — plugin discovery
- `OrchestratorPluginInterface`, `OrchestratorPluginBase` — plugin contracts
- `OrchestratorInterface` — base orchestrator contract
- `InterruptExceptionInterface`, `FlowDropInterruptException` — interrupt contracts

Concrete orchestrator implementations (e.g., `SynchronousOrchestratorPlugin`) and helper services remain `@internal`. See the [Orchestrator Plugin API Reference](../reference/api/orchestrator.md) for full details and the [BC Policy](../reference/api/bc-policy.md) for stability guarantees.

### Services

| Service ID | Class | Description |
|-----------|-------|-------------|
| `flowdrop_orchestration.plugin_manager` | `OrchestratorPluginManager` | Discovers orchestrator plugins via PHP 8 attributes |
| `flowdrop_orchestration.helper` | `OrchestratorHelper` | Resolves orchestrators, provides fallback handling and form option builders |

## References

- [flowdrop_runtime](flowdrop_runtime.md) — provides the standard orchestrators
- [flowdrop_stategraph](flowdrop_stategraph.md) — provides the stateful graph orchestrator
- [Workflow Snapshots and Orchestrators](../development/workflow-snapshots-and-orchestrators.md)
