# FlowDrop Development Guide

> For coding conventions, patterns, testing guidelines, and AI assistant context, see [AGENTS.md](AGENTS.md).

## Prerequisites

| Tool       | Version    |
| ---------- | ---------- |
| PHP        | 8.2+       |
| Drupal     | 11         |
| Composer   | 2.x        |
| Node.js    | 18+        |
| DDEV       | latest     |

## Local Development Setup

This project uses **DDEV** with the [drupal-contrib addon](https://github.com/ddev/ddev-drupal-contrib).

```bash
# Start the environment
ddev start

# Install PHP dependencies
ddev composer install

# Install the site
ddev drush si --existing-config -y

# Enable core FlowDrop modules
ddev drush en flowdrop flowdrop_workflow flowdrop_runtime flowdrop_stategraph \
  flowdrop_pipeline flowdrop_job flowdrop_node_type flowdrop_node_category \
  flowdrop_node_processor flowdrop_trigger flowdrop_ui_components -y

# Clear cache
ddev drush cr

# Open in browser
ddev launch
```

Site URL: `https://flowdrop.ddev.site`

## Code Quality

All quality tools are available via the DDEV drupal-contrib addon:

```bash
ddev phpcbf               # Auto-fix coding standard violations
ddev phpcs                # Check remaining violations
ddev phpstan              # Static analysis (level 5)
ddev phpunit modules/flowdrop_runtime/tests/   # Run tests for a module
```

Run these after every change. See [AGENTS.md — After Making Changes](AGENTS.md#after-making-changes) for the full workflow.

## Frontend (Svelte Editor)

The workflow editor UI is built with Svelte 5 + XYFlow. Source lives in `modules/flowdrop_ui_components/lib/flowdrop/`.

```bash
cd modules/flowdrop_ui_components/lib/flowdrop

# Install dependencies
npm install

# Development build (watch)
npm run dev

# Production build
npm run build
```

The build outputs ES module chunks consumed by `flowdrop_ui_components.libraries.yml`. The `window.FlowDrop` global is assigned via `src/lib/main.ts`.

See [AGENTS.md — Key Files Reference](AGENTS.md#key-files-reference) for the full list of important source files.

## Module Overview

| Module                             | Purpose                                     |
| ---------------------------------- | ------------------------------------------- |
| `flowdrop`                         | Core plugin system, node processor base     |
| `flowdrop_workflow`                | Workflow config entity management           |
| `flowdrop_runtime`                 | Workflow execution engine                   |
| `flowdrop_stategraph`              | State graph orchestration (loops, branches) |
| `flowdrop_pipeline`                | Pipeline (queued execution) management      |
| `flowdrop_job`                     | Individual job execution                    |
| `flowdrop_node_type`               | Node type config entities                   |
| `flowdrop_node_category`           | Node categorization                         |
| `flowdrop_node_processor`          | Built-in node processors                    |
| `flowdrop_trigger`                 | Event-driven workflow triggers              |
| `flowdrop_interrupt`               | Human-in-the-loop interrupt handling        |
| `flowdrop_ui_components`           | Drupal SDC components + Svelte editor       |
| `flowdrop_playground`              | Development/testing sandbox                 |
| `flowdrop_orchestration_connector` | External orchestrator integration           |

## Useful Drush Commands

```bash
ddev drush cr                                      # Clear cache
ddev drush watchdog:tail --filter=flowdrop         # Watch FlowDrop logs
ddev drush ev "print_r(\Drupal::service('flowdrop.node_processor_plugin_manager')->getDefinitions());"
                                                   # Inspect discovered plugins
ddev drush flowdrop:trigger:list                   # List active triggers
ddev drush flowdrop:trigger:test entity.insert node 1  # Test a trigger
```

## Further Reading

- [AGENTS.md](AGENTS.md) — Architecture, coding standards, patterns, testing, debugging
- [docs/development/flowdrop-node-processor.md](docs/development/flowdrop-node-processor.md) — Node processor reference
- [docs/development/internal-parameters.md](docs/development/internal-parameters.md) — Internal parameter system
- [docs/development/gateway-nodes.md](docs/development/gateway-nodes.md) — Branches and gateway nodes
- [docs/development/execution-dependency-rules.md](docs/development/execution-dependency-rules.md) — Execution rules
- [docs/meta/glossary.md](docs/meta/glossary.md) — Project terminology
- [modules/flowdrop_trigger/TESTING.md](modules/flowdrop_trigger/TESTING.md) — Trigger testing guide
