# FlowDrop Playground

> Interactive chat-based interface for testing and debugging workflows with real-time execution feedback.

## Overview

The `flowdrop_playground` module provides an interactive testing environment for workflows. It presents a chat-like interface where you can send messages to a workflow, see real-time execution progress, handle interrupts inline, and inspect session state — all without setting up triggers or external integrations.

The playground uses the [StateGraph orchestrator](flowdrop_stategraph.md) for execution and builds on [sessions](flowdrop_session.md) for multi-turn conversation tracking. It's the fastest way to test and iterate on workflow designs.

## Dependencies

- [flowdrop_session](flowdrop_session.md) (session and message management)
- [flowdrop_stategraph](flowdrop_stategraph.md) (stateful execution)
- [flowdrop_ui_components](flowdrop_ui_components.md) (UI components)

## Configuration

### Admin Pages

| Path | Description |
|------|-------------|
| `/admin/flowdrop/config/playground` | Playground settings |
| `/admin/flowdrop/workflows/{workflow_id}/playground` | Open the playground for a specific workflow |

### Permissions

| Permission | Description |
|------------|-------------|
| `administer flowdrop_playground` | Access to playground settings. Restricted. |
| `execute playground workflow` | Use the playground to test workflows |

## Tips and Tricks

### Accessing the Playground

From the workflow list at `/admin/flowdrop/workflows`, each workflow has a "Playground" action link. You can also navigate directly to `/admin/flowdrop/workflows/{workflow_id}/playground`.

### Session Management

Each playground interaction creates a session. You can:

- Create multiple sessions for the same workflow to test different scenarios
- View message history within a session
- Reset a session to start over
- Delete old sessions to clean up

### Interrupt Handling

When a workflow triggers an [interrupt](flowdrop_interrupt.md) (confirmation, choice, text input, or form), the playground UI renders the appropriate input inline in the chat. You can respond directly without leaving the page.

### Debugging Workflows

The playground shows real-time execution status as nodes execute. Combined with the message history, this makes it easy to trace data flow and identify issues in your workflow logic.

## Developer API

### API Endpoints

**Session Management:**

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/flowdrop/workflows/{workflow_id}/playground/sessions` | List sessions for a workflow |
| POST | `/api/flowdrop/workflows/{workflow_id}/playground/sessions` | Create a new session |
| GET | `/api/flowdrop/playground/sessions/{session_id}` | Get session details |
| DELETE | `/api/flowdrop/playground/sessions/{session_id}` | Delete a session |

**Messages:**

| Method | Path | Description |
|--------|------|-------------|
| GET | `/api/flowdrop/playground/sessions/{session_id}/messages` | Get message history |
| POST | `/api/flowdrop/playground/sessions/{session_id}/messages` | Send a message |
| GET | `/api/flowdrop/playground/sessions/{session_id}/messages/{message_id}` | Get a specific message |
| GET | `/api/flowdrop/playground/sessions/{session_id}/messages/{message_id}/status` | Poll message processing status |

**Execution Control:**

| Method | Path | Description |
|--------|------|-------------|
| POST | `/api/flowdrop/playground/sessions/{session_id}/stop` | Stop current execution |
| POST | `/api/flowdrop/playground/sessions/{session_id}/reset` | Reset session to idle state |

## References

- [flowdrop_session](flowdrop_session.md) — session and message entities
- [flowdrop_stategraph](flowdrop_stategraph.md) — execution orchestrator
- [flowdrop_interrupt](flowdrop_interrupt.md) — inline interrupt handling
