# Key Concepts

This page explains the core concepts you need to understand when working with FlowDrop.

## Workflows

A **workflow** is a series of steps connected together to accomplish a task. Think of it as a flowchart that actually runs. Workflows are stored as Drupal configuration entities, meaning they can be exported, imported, and version-controlled.

## Nodes

Each step in a workflow is called a **node**. Nodes are the building blocks — they take input, process it, and produce output.

FlowDrop includes 25+ built-in nodes organized into categories:

| Category | Examples |
|----------|----------|
| **Data Processing** | DataShaper, DataExtractor, SplitText, RegexExtractor |
| **Control Flow** | SwitchGateway, BooleanGateway, IfElse, ForEach |
| **Entity Operations** | EntityQuery, EntityContext, EntitySave |
| **Text & Output** | TextInput, TextOutput, PromptTemplate, Logger |
| **HTTP & Integration** | HttpRequest |
| **AI Integration** | ChatModel |
| **Human-in-the-Loop** | ConfirmationNode, ChoiceNode, TextInputNode |
| **Workflow Execution** | WorkflowExecutor, WorkflowResultsRetriever |
| **Utility** | DateTime, Calculator, Note |

![Anatomy of a workflow](../screenshots/visual-editor-workflow.png)

### Node Visual Types

Nodes appear in different shapes depending on their function:

- **Standard** — Rectangular nodes for most processors
- **Simple** — Compact nodes for lightweight operations
- **Gateway** — Diamond-shaped nodes for branching logic (IfElse, SwitchGateway)

![Different node visual types](../screenshots/workflow-with-triggers.png)

## Edges (Connections)

**Edges** connect nodes together. There are two types:

- **Data Edges** — Pass data from one node's output to another node's input. Think of these as pipes that carry values.
- **Trigger Edges** — Control whether a node executes. These act like switches — they determine the execution path.

## Ports

**Ports** are the connection points on nodes where edges attach.

- **Input Ports** (left side of a node) — Where data comes in
- **Output Ports** (right side of a node) — Where data goes out

Ports are color-coded by data type, so you can quickly see what kind of data a connection carries:

| Data Type | Color | Aliases |
|-----------|-------|---------|
| String | Emerald | `text` |
| Number | Blue | `integer`, `float` |
| Boolean | Purple | |
| Array | Amber | `list` |
| Object | Orange | `json` |
| Mixed | Orange | |
| URL | Cyan | `email` |
| Date | Lime | `datetime`, `time` |
| File | Red | `document` |
| Image | Pink | `picture` |
| Trigger | Dark gray | |

![Port data type colors](../screenshots/editor-layout.png)

!!! tip
    Same-type ports connect to same-type ports. If you need to convert between types, use a processing node (like DataShaper) in between.

## Execution

When you run a workflow, FlowDrop:

1. **Resolves the execution order** — Nodes execute in dependency order (a node won't run until all its inputs are ready).
2. **Executes each node** — Starting from nodes with no dependencies, working forward.
3. **Passes data through edges** — Output from one node flows into the next via edges.
4. **Records results** — Each node's execution is tracked for monitoring and debugging.

## Pipelines and Jobs

- **Pipeline** — One complete run of a workflow. When you execute a workflow, a pipeline is created.
- **Job** — One node's execution within a pipeline. Each node that runs creates a job.

For example, if your workflow has 5 nodes and you execute it once, you get 1 pipeline with 5 jobs.

You can monitor pipelines and jobs through the admin UI to track progress, view outputs, and debug failures.

## Orchestrators

**Orchestrators** control _how_ a workflow runs. FlowDrop provides three:

| Orchestrator | When to use |
|-------------|-------------|
| **Synchronous** | Simple workflows where you need an immediate result. Runs all nodes in one request. |
| **Asynchronous** | Background processing for longer workflows. Uses Drupal's queue system for scalability. |
| **StateGraph** | Advanced workflows that need loops, chat interactions, or human-in-the-loop. Supports checkpointing and resumption. |

## Triggers

**Triggers** automatically start workflows when Drupal events happen. Instead of manually executing a workflow, you can configure it to run when:

- **Entity events** — A content item is created, updated, or deleted
- **User events** — A user logs in or logs out
- **Cron events** — Drupal's cron runs on schedule

Triggers are configured by adding a Trigger node in the workflow editor. See the [Setting Up Triggers](../guide/triggers.md) guide for step-by-step instructions.

## Node Types

**Node Types** are configurable wrappers around Node Processors. A single Node Processor (defined in code) can have multiple Node Types, each with different default settings.

For example, the `TextInput` processor could have Node Types like "Email Subject Input" and "Body Text Input" — same processor, different default configurations. Site administrators manage Node Types at **Administration > Structure > FlowDrop Node Type**.

## Next Steps

- **[Quick Start](quick-start.md)** — Build your first workflow
- **[Node Reference](../guide/nodes/index.md)** — Detailed documentation for all built-in nodes
- **[Execution Modes](../guide/execution-modes.md)** — Learn about orchestrators and queue processing
- **[Creating Workflows](../guide/workflows/creating-workflows.md)** — Manage workflows via the admin UI
- **[Connecting Nodes](../guide/workflows/connecting-nodes.md)** — Deep dive into ports and data types
