orkestr 1.0.0

data/README.md

@@ -0,0 +1,832 @@
+# Orkestr
+
+Rails Engine for building and executing workflows. Define workflows as directed graphs of nodes, execute them with a pluggable parallel engine, and integrate human tasks, triggers, and custom plugins.
+
+<p align="center">
+  <img src="docs/screenshots/01-dashboard.png" alt="Workflow Dashboard" width="800" />
+</p>
+
+## Features
+
+- **Graph-based workflows** — directed acyclic graph of nodes connected by edges
+- **Parallel execution** — nodes in independent branches run concurrently via `concurrent-ruby`
+- **Conditional branching** — route execution based on conditions with `source_handle` edges
+- **Join/merge** — converge parallel branches with `join: all` or `join: any` semantics
+- **Wait/resume** — pause execution and resume later with external data
+- **Human-in-the-loop** — create tasks with form schemas, assignees, deadlines, and response validation
+- **Contextualizable** — attach workflows to any host app model (polymorphic)
+- **Reusable contexts** — optionally reuse an active context for the same entity/workflow
+- **Execution logging** — structured logs (debug/info/warn/error) from nodes and triggers
+- **Plugin system** — auto-discovered nodes and triggers with JSON Schema DSL
+- **REST API** — full CRUD for workflows, executions, human tasks, and registry
+- **Visual editor** — React Flow web component (`<orkestr-editor>`) with Shadow DOM isolation
+- **Workflow management** — duplicate, export (JSON), and import workflows
+- **Webhook triggers** — HTTP webhook with optional secret verification
+- **Scheduled triggers** — cron-based scheduling via `fugit`
+- **Cycle detection** — DFS-based detection prevents infinite graph loops (configurable via `allow_cycles`)
+- **Async execution** — optional background job execution via configurable job backend
+- **Expression system** — n8n-like `{{ input.x }}`, `{{ context.x }}`, `{{ nodes.<id>.x }}` expressions resolved at runtime in node configs
+- **Action node with Ruby sandbox** — execute Ruby code in node configs with access to `input`, `context`, `output`, and optional context updates
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "orkestr"
+```
+
+Then run:
+
+```bash
+bundle install
+rake orkestr:install:migrations
+rake db:migrate
+```
+
+Mount the engine in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  mount Orkestr::Engine => "/orkestr"
+end
+```
+
+## Configuration
+
+Create an initializer `config/initializers/orkestr.rb`:
+
+```ruby
+Orkestr.configure do |config|
+  # Additional paths to load custom node plugins
+  config.nodes_paths = [Rails.root.join("app/workflow_nodes")]
+
+  # Additional paths to load custom trigger plugins
+  config.triggers_paths = [Rails.root.join("app/workflow_triggers")]
+
+  # Job backend: :async (default) or :sidekiq
+  config.job_backend = :async
+
+  # Authentication (optional) — receives the request, returns the current user or nil
+  config.authenticator = ->(request) {
+    token = request.headers["Authorization"]&.sub("Bearer ", "")
+    User.find_by(api_token: token) if token.present?
+  }
+
+  # Authorization (optional) — receives the current user and request
+  config.authorizer = ->(user, request) {
+    user.admin?
+  }
+end
+```
+
+### Options
+
+| Option | Default | Description |
+|---|---|---|
+| `nodes_paths` | `[]` | Additional paths to load custom node plugins |
+| `triggers_paths` | `[]` | Additional paths to load custom trigger plugins |
+| `job_backend` | `:async` | Background job backend (`:async` or `:sidekiq`) |
+| `authenticator` | `nil` | Callable for API authentication (open access when nil) |
+| `authorizer` | `nil` | Callable for API authorization |
+| `custom_ui_scripts` | `[]` | JS asset paths to inject into the engine's built-in UI page (for custom field types, etc.) |
+| `custom_ui_styles` | `[]` | CSS asset paths to inject into host app pages (for theming the web component) |
+| `allow_cycles` | `false` | Allow cyclic graphs (loops). The Runner's MAX_ITERATIONS (1000) prevents runaway loops at execution time |
+
+## Web UI
+
+Orkestr ships a built-in visual editor powered by React Flow, delivered as a Web Component. Access it at:
+
+```
+http://localhost:3000/orkestr/ui
+```
+
+### Visual Workflow Editor
+
+Design workflows visually with drag-and-drop nodes, conditional branching, and parallel paths.
+
+| Document Review | Data Pipeline | Employee Onboarding |
+|:---:|:---:|:---:|
+| ![Document Review](docs/screenshots/02-workflow-editor.png) | ![Data Pipeline](docs/screenshots/08-pipeline-workflow.png) | ![Onboarding](docs/screenshots/07-onboarding-workflow.png) |
+| Conditional branching (approve/reject) | HTTP + Transform + parallel fan-out | Parallel human tasks + join |
+
+### Node Configuration
+
+Click any node to configure it. The right panel shows node-specific settings, expression fields (`{x}` buttons), and the form builder for human tasks.
+
+<p align="center">
+  <img src="docs/screenshots/03-node-config-panel.png" alt="Node Configuration Panel" width="800" />
+</p>
+
+### Human Task Forms
+
+Rich form fields including text, textarea, checkbox, select (static + dynamic), multi-select, date, email, URL, and custom field types (slider, rating) registered by the host app.
+
+<p align="center">
+  <img src="docs/screenshots/05-human-task-form.png" alt="Human Task Form" width="600" />
+</p>
+
+### Embedding in your app
+
+The `<orkestr-editor>` Web Component works in any frontend stack:
+
+```erb
+<!-- ERB -->
+<%= orkestr_editor_tag api_base_url: "/orkestr" %>
+
+<!-- Or manually -->
+<script src="/assets/orkestr/orkestr-editor.js" defer></script>
+<orkestr-editor api-base-url="/orkestr" mode="dashboard" style="display:block;width:100%;height:100vh;"></orkestr-editor>
+```
+
+```html
+<!-- Vue / Any HTML -->
+<orkestr-editor api-base-url="/orkestr" auth-token="your-token" mode="dashboard"></orkestr-editor>
+```
+
+### Attributes
+
+| Attribute | Default | Description |
+|---|---|---|
+| `api-base-url` | `/orkestr` | Engine mount path |
+| `auth-token` | - | Bearer token for API authentication |
+| `mode` | `dashboard` | `dashboard` (full UI), `editor` (single workflow), or `task` (task form only) |
+| `workflow-id` | - | Open a specific workflow in editor mode |
+| `task-id` | - | Task to display when `mode="task"` |
+| `prefill` | - | JSON string of pre-filled form values (used with `mode="task"`) |
+
+### Task form mode
+
+Use `mode="task"` to embed a human task form without any dashboard chrome. The form is rendered entirely by the web component — no server-side form rendering needed. This keeps Orkestr frontend-agnostic: the host app only provides the container (modal, panel, page…).
+
+```html
+<!-- Embed in any container — modal, panel, sidebar, page -->
+<orkestr-editor
+  api-base-url="/orkestr"
+  auth-token="session-or-api-token"
+  mode="task"
+  task-id="<task-uuid>"
+  style="display:block;min-height:200px;">
+</orkestr-editor>
+
+<script>
+  // React to task lifecycle events
+  document.addEventListener("orkestr:task-completed", function(e) {
+    console.log("Task completed:", e.detail.taskId);
+    // Close your modal, reload page, etc.
+  });
+</script>
+```
+
+With the Rails helper:
+
+```erb
+<%= orkestr_editor_tag mode: "task", task_id: @task.id, auth_token: session_token %>
+```
+
+The engine also provides a standalone HTML page at `/orkestr/human_tasks/:id` that uses this mode — useful as a fallback or for direct links.
+
+### Custom Events
+
+The component dispatches DOM events (with `composed: true` to cross Shadow DOM boundaries):
+
+| Event | Detail | Fired when |
+|---|---|---|
+| `orkestr:workflow-saved` | `{ workflowId }` | A workflow is saved in the editor |
+| `orkestr:execution-started` | `{ executionId, workflowId }` | A workflow execution starts |
+| `orkestr:task-completed` | `{ taskId }` | A human task form is submitted |
+| `orkestr:task-cancelled` | `{ taskId }` | A human task form is cancelled |
+
+### Building UI assets
+
+The gem ships with pre-built assets. To rebuild during development:
+
+```bash
+rake orkestr:build_ui
+```
+
+## Usage
+
+### Creating a workflow
+
+```ruby
+workflow = Orkestr::Workflow.create!(
+  name: "My Workflow",
+  status: "published",
+  trigger_type: "manual",
+  default_context: { team: "engineering" },
+  reuse_context: false,
+  graph_json: {
+    nodes: [
+      { id: "1", type: "transform", data: { type: "transform", mappings: [...] } },
+      { id: "2", type: "http_request", data: { type: "http_request", url: "..." } }
+    ],
+    edges: [
+      { id: "e1", source: "1", target: "2" }
+    ]
+  }
+)
+
+# Sync the graph to the database (automatic on API create/update)
+Orkestr::WorkflowSynchronizer.new(workflow).call
+```
+
+### Running a workflow
+
+```ruby
+# Synchronous execution
+execution = Orkestr::ExecutionService::Start.new(
+  workflow,
+  context: { key: "value" }
+).call
+
+# With a contextualizable entity
+execution = Orkestr::ExecutionService::Start.new(
+  workflow,
+  context: { key: "value" },
+  contextualizable: document
+).call
+
+# Async execution (via configured job backend)
+execution = Orkestr::ExecutionService::Start.new(
+  workflow,
+  context: {},
+  async: true
+).call
+```
+
+### Workflow management
+
+```ruby
+# Duplicate
+copy = Orkestr::WorkflowService::Duplicate.new(workflow, name: "My Copy").call
+
+# Export to JSON
+data = Orkestr::WorkflowService::Export.new(workflow).call
+json = Orkestr::WorkflowService::Export.new(workflow).to_json
+
+# Import from JSON
+workflow = Orkestr::WorkflowService::Import.new(data).call
+```
+
+### Contexts
+
+Contexts carry data through a workflow execution and can be linked to host app models:
+
+```ruby
+# Reuse context: when enabled, subsequent executions for the same
+# entity + workflow reuse the active context instead of creating a new one
+workflow.update!(reuse_context: true)
+
+# Default context: merged into every execution's context
+workflow.update!(default_context: { team: "engineering", priority: "normal" })
+
+# Query contexts
+Orkestr::Context.active                    # pending or processing
+Orkestr::Context.for_entity(document)      # contexts for a specific entity
+Orkestr::Context.for_workflow(workflow)     # contexts for a specific workflow
+```
+
+### Human Tasks
+
+Workflows can pause for human input using the `human_action` node:
+
+```ruby
+# Query pending tasks
+tasks = Orkestr::HumanTask.pending
+
+# Complete a task (validates response against schema, resumes the workflow)
+Orkestr::HumanTaskService::Complete.new(task, response: { approved: true }).call
+```
+
+#### Displaying task forms
+
+The recommended way to display human task forms is via the web component in `mode="task"`. This keeps the engine frontend-agnostic — the host app controls the container (modal, panel, page) and reacts to DOM events:
+
+```html
+<orkestr-editor api-base-url="/orkestr" auth-token="..." mode="task" task-id="<uuid>">
+</orkestr-editor>
+```
+
+See [Task form mode](#task-form-mode) for details and examples.
+
+#### Task Actions
+
+Human action nodes support an `actions` config that defines multiple entry points (buttons) for the same task. This is useful for approval/rejection workflows, multi-choice tasks, or any scenario where different actions require different forms.
+
+```yaml
+# In node config (graph_json or workflow YAML)
+actions:
+  - label: "Approve"
+    icon: "check-circle"
+    color: "#16a34a"
+    prefill:
+      decision: "approve"
+    schema:
+      type: object
+      properties:
+        comment:
+          type: string
+          format: text
+          description: "Optional comment"
+  - label: "Reject"
+    icon: "x-circle"
+    color: "#dc2626"
+    prefill:
+      decision: "reject"
+    schema:
+      type: object
+      required: ["reason"]
+      properties:
+        reason:
+          type: string
+          format: select
+          description: "Rejection reason"
+          options:
+            - { label: "Non-compliant", value: "non_compliant" }
+            - { label: "Incomplete", value: "incomplete" }
+        comment:
+          type: string
+          format: text
+          description: "Comment"
+```
+
+Each action can define:
+
+| Property | Required | Description |
+|---|---|---|
+| `label` | Yes | Button text displayed to the user |
+| `icon` | No | Icon name (e.g. Lucide icon names) |
+| `color` | No | Hex color for the button (e.g. `#16a34a`) |
+| `prefill` | No | Key-value pairs pre-filled in the form and hidden from the user |
+| `schema` | No | Per-action form schema that replaces the node's base `form_schema` |
+
+**How it works:**
+- In the **task list**, each action renders as a separate colored button
+- When an action has its own `schema`, only that schema's fields are shown
+- When no `schema` is defined, the base `form_schema` is used with prefilled fields hidden
+- The `prefill` values are always included in the submitted response
+- Actions are fully configurable in the visual workflow editor via the "Task Actions" panel
+
+#### Form field types
+
+The form schema supports all common field types via `type` + `format`:
+
+| Type | Format | Renders as |
+|---|---|---|
+| `string` | _(none)_ | Text input |
+| `string` | `text` | Textarea |
+| `string` | `date` | Date picker |
+| `string` | `email` | Email input |
+| `string` | `url` | URL input |
+| `string` | `file` | File upload (base64) |
+| `string` | `select` | Select dropdown |
+| `number` | _(none)_ | Number input |
+| `boolean` | _(none)_ | Checkbox |
+
+#### Select fields
+
+Select fields support static options, dynamic options from an API, and multiple selection:
+
+```json
+{
+  "type": "string",
+  "format": "select",
+  "multiple": true,
+  "options": [
+    { "label": "Option A", "value": "a" },
+    { "label": "Option B", "value": "b" }
+  ],
+  "options_url": "/api/users?format=options"
+}
+```
+
+The `options_url` endpoint should return a JSON array. Accepted formats:
+- `[{ "label": "...", "value": "..." }]`
+- `[{ "name": "...", "id": "..." }]`
+- `["string1", "string2"]`
+
+Static and dynamic options are merged.
+
+#### Custom field types (host app)
+
+Host apps can register custom field renderers that appear in both the workflow editor's form builder (type dropdown + config UI) and in human task forms at runtime.
+
+**1. Create a JS file** in your app's assets (e.g. `app/assets/javascripts/orkestr_custom_fields.js`):
+
+```javascript
+document.addEventListener("DOMContentLoaded", function () {
+  if (!window.OrkestrEditor) return;
+
+  OrkestrEditor.registerFieldType("slider", {
+    label: "Slider",  // displayed in the type dropdown
+    // Render the field in human task forms
+    render: function (container, ctx) {
+      var field = ctx.field;
+      var input = document.createElement("input");
+      input.type = "range";
+      input.min = field.min || 0;
+      input.max = field.max || 100;
+      input.step = field.step || 1;
+      input.value = ctx.value || 50;
+      input.addEventListener("input", function () {
+        ctx.onChange(Number(input.value));
+      });
+      container.appendChild(input);
+    },
+    // Render config UI in the workflow editor's form builder (optional)
+    configRender: function (container, ctx) {
+      var field = ctx.field;
+      ["min", "max", "step"].forEach(function (key) {
+        var label = document.createElement("label");
+        label.className = "ork-label";
+        label.textContent = key.charAt(0).toUpperCase() + key.slice(1);
+        var input = document.createElement("input");
+        input.className = "ork-input";
+        input.type = "number";
+        input.value = field[key] || "";
+        input.addEventListener("change", function () {
+          var patch = {};
+          patch[key] = input.value ? Number(input.value) : undefined;
+          ctx.onChange(patch);
+        });
+        var group = document.createElement("div");
+        group.className = "ork-form-group";
+        group.appendChild(label);
+        group.appendChild(input);
+        container.appendChild(group);
+      });
+    },
+  });
+});
+```
+
+**2. Configure Orkestr** to inject this script into the engine's built-in UI page (`/orkestr/ui`):
+
+```ruby
+# config/initializers/orkestr.rb
+Orkestr.configure do |config|
+  config.custom_ui_scripts = ["orkestr_custom_fields"]
+end
+```
+
+**3. Include in your app layout** (for human task forms rendered in host app pages):
+
+```erb
+<%= javascript_include_tag "orkestr_custom_fields" %>
+```
+
+**API reference:**
+
+| Callback | Context | Description |
+|---|---|---|
+| `render(container, ctx)` | `ctx.value` — current value, `ctx.field` — full field schema, `ctx.onChange(value)` — update value | Renders the field in task forms |
+| `configRender(container, ctx)` | `ctx.field` — current field config, `ctx.onChange(patch)` — merge config patch | Renders admin config UI in the form builder (e.g. min/max/step for a slider) |
+
+Extra properties set via `configRender` (like `min`, `max`, `step`) are persisted in the schema and passed to `render` as `ctx.field` properties at runtime.
+
+### Assignable models
+
+Make your models assignable to receive human tasks:
+
+```ruby
+class User < ApplicationRecord
+  include Orkestr::Assignable
+end
+
+# Find users with pending tasks
+User.with_pending_tasks
+
+# Find users with overdue tasks
+User.with_overdue_tasks
+```
+
+### Contextualizable models
+
+Make your models contextualizable to track workflow contexts:
+
+```ruby
+class Document < ApplicationRecord
+  include Orkestr::Contextualizable
+end
+
+# Access contexts for a document
+document.orkestr_contexts
+```
+
+### Entry conditions
+
+Triggers can define entry conditions to restrict which entities or contexts are allowed to start a workflow. Conditions are stored in `trigger_config` and evaluated before execution starts.
+
+```ruby
+workflow.update!(trigger_config: {
+  entry_conditions: {
+    rules: [
+      # Only allow Document entities
+      { field: "contextualizable_type", operator: "eq", value: "Document" },
+      # Only when document status is one of these
+      { field: "status", operator: "in", value: %w[pending_review draft] }
+    ],
+    match: "all"  # "all" (AND) or "any" (OR)
+  }
+})
+```
+
+The evaluation payload is built from (in order of priority):
+1. `contextualizable_type` — the entity's class name
+2. Entity attributes (`entity.attributes`) — all model columns
+3. Context data — the hash passed at execution time
+
+Available operators: `eq`, `neq`, `gt`, `lt`, `contains`, `present`, `blank`, `in`.
+
+When conditions are not met, `ExecutionService::Start` raises `Orkestr::EntryConditionNotMetError` (HTTP 403 via API).
+
+### Expression System
+
+Node configuration fields support dynamic expressions resolved at runtime, similar to n8n. Expressions use the `{{ path }}` syntax:
+
+| Prefix | Source | Example |
+|---|---|---|
+| `input` | Output from the previous node | `{{ input.user_id }}` |
+| `context` | Workflow context data | `{{ context.team }}` |
+| `nodes.<id>` | Output of a specific node (by react_flow_id) | `{{ nodes.fetch_user.email }}` |
+
+```ruby
+# Single expression — preserves the raw type (number, boolean, etc.)
+"{{ input.count }}"  # => 42 (integer, not "42")
+
+# Mixed content — interpolated as string
+"Hello {{ context.name }}, you have {{ input.count }} items"
+# => "Hello Alice, you have 42 items"
+```
+
+Expressions are resolved by `ExpressionResolver` in `NodeRunner` before passing config to the plugin. The visual editor includes an expression picker (`{x}` button) that lists available variables from predecessor nodes and workflow context.
+
+### Action Node (Ruby Code)
+
+The `action` node executes Ruby code in a sandboxed environment. Available variables:
+
+| Variable | Description |
+|---|---|
+| `input` | Hash — output from the previous node (frozen) |
+| `context` | Hash — workflow context data (frozen) |
+| `output` | Hash — fill this to produce the node's output |
+| `dig(data, "path")` | Helper to navigate nested hashes with dot notation |
+
+```ruby
+# Example: compute a total and update the workflow context
+# Config: code
+output[:total] = input[:price] * input[:quantity]
+output[:processed_at] = Time.current.iso8601
+
+# Config: update_context = true
+# → output is merged into the workflow context for downstream nodes
+```
+
+```ruby
+# Example: aggregate data from an array
+output[:total_items] = input[:items].sum { |i| i[:qty] }
+output[:names] = input[:items].map { |i| i[:name] }.join(", ")
+```
+
+Safety: code runs with a **10-second timeout** to prevent infinite loops. When `update_context` is enabled, the output hash is merged into the workflow's `Context#data`.
+
+### Execution logging
+
+Nodes and triggers can log structured messages during execution:
+
+```ruby
+# Inside a node's execute method
+def execute(context, input)
+  log("Processing document", level: :info, metadata: { doc_id: input[:id] })
+  # ...
+end
+
+# Query logs
+Orkestr::ExecutionLog.errors                      # error-level logs
+Orkestr::ExecutionLog.for_level("info")           # specific level
+Orkestr::ExecutionLog.recent                      # ordered by created_at desc
+```
+
+## API Endpoints
+
+All endpoints are namespaced under `/orkestr/api/`. When an `authenticator` is configured, requests must include valid credentials.
+
+### Workflows
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/api/workflows` | List all workflows |
+| `GET` | `/api/workflows/:id` | Show workflow with nodes & edges |
+| `POST` | `/api/workflows` | Create a workflow |
+| `PUT` | `/api/workflows/:id` | Update a workflow |
+| `DELETE` | `/api/workflows/:id` | Delete a workflow |
+
+### Executions
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/api/workflows/:workflow_id/executions` | List executions (filterable by `status`) |
+| `GET` | `/api/executions/:id` | Show execution with node executions |
+| `POST` | `/api/workflows/:workflow_id/executions` | Start a new execution |
+
+The create endpoint accepts optional `contextualizable_type` and `contextualizable_id` parameters to attach the execution to a host app model.
+
+### Human Tasks
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/api/human_tasks` | List tasks (filterable by `status`, `assignable_type`, `assignable_id`) |
+| `GET` | `/api/human_tasks/:id` | Show task with schema & assignees |
+| `PUT` | `/api/human_tasks/:id/complete` | Submit response and resume workflow |
+
+### Registry
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/api/registry/nodes` | List available node plugins with schemas |
+| `GET` | `/api/registry/triggers` | List available trigger plugins with schemas |
+
+### Webhooks
+
+| Method | Path | Description |
+|---|---|---|
+| `POST` | `/webhooks/:workflow_id` | Trigger a workflow via webhook |
+
+Webhook requests pass the request body as context. When a `secret` is configured on the trigger, the request must include a matching `X-Orkestr-Secret` header.
+
+## Creating Custom Plugins
+
+### Custom Node
+
+Create a file in `app/orkestr_nodes/my_node/node.rb`:
+
+```ruby
+module Orkestr
+  module Nodes
+    class MyNode < Base
+      node_id "my_node"
+      label "My Custom Node"
+      category "custom"
+
+      config_schema do
+        string :api_key, description: "API key for the service"
+      end
+
+      input_schema do
+        string :data, description: "Input data"
+      end
+
+      output_schema do
+        string :result, description: "Processed result"
+      end
+
+      def execute(context, input)
+        # Available helpers:
+        #   config        — node configuration (from config_json)
+        #   execution     — parent Execution record
+        #   node_execution — current NodeExecution record
+        #   workflow_context — execution context data
+        #   log(message, level:, metadata:) — structured logging
+        #   dig_value(hash, "nested.key") — dot-notation access
+        #   interpolate(template, variables) — {{var}} interpolation
+        #
+        # Return a hash — it becomes the output passed to downstream nodes
+        { result: "processed" }
+      end
+    end
+  end
+end
+```
+
+Nodes are auto-discovered from:
+1. `orkestr/app/orkestr_nodes/` (built-in)
+2. `app/orkestr_nodes/` in the host app
+3. Paths in `Orkestr.configuration.nodes_paths`
+
+### Custom Trigger
+
+Create a file in `app/orkestr_triggers/my_trigger/trigger.rb`:
+
+```ruby
+module Orkestr
+  module Triggers
+    class MyTrigger < Base
+      trigger_id "my_trigger"
+      label "My Custom Trigger"
+
+      config_schema do
+        string :channel, description: "Channel to listen on"
+      end
+
+      def fire(context = {})
+        # Available helpers:
+        #   workflow       — associated Workflow record
+        #   trigger_config — trigger configuration (symbolized keys)
+        #   log(message, execution:, level:, metadata:) — structured logging
+        #   start_execution(context, async:) — create and run execution
+        start_execution(context)
+      end
+    end
+  end
+end
+```
+
+### Built-in Nodes
+
+| Node | Category | Description |
+|---|---|---|
+| `action` | general | Execute Ruby code in a sandbox with access to `input`, `context`, and `output`. Optionally merge output into workflow context. 10s timeout |
+| `transform` | data | Map, rename, and template data fields with dot-notation and `{{var}}` interpolation |
+| `condition` | logic | Conditional branching with operators: `eq`, `neq`, `gt`, `lt`, `contains`, `present`, `blank`. Supports `match: all` or `match: any` for multiple rules |
+| `http_request` | integration | HTTP requests (GET, POST, PUT, DELETE) with URL/body interpolation, configurable headers, 30s timeout |
+| `wait` | flow | Pause execution until externally resumed via `ExecutionService::Complete` |
+| `human_action` | human | Create a human task with form schema, assignees (polymorphic), deadlines, and wait for completion |
+
+### Built-in Triggers
+
+| Trigger | Description |
+|---|---|
+| `manual` | Start a workflow on demand |
+| `scheduled` | Cron-based scheduling (uses `fugit` for parsing) |
+| `webhook` | HTTP webhook with optional secret verification (`X-Orkestr-Secret` header) |
+
+## Execution Engine
+
+### How it works
+
+1. **Start** — creates an `Execution` and `Context`, identifies start nodes (no incoming edges), creates initial `NodeExecution` records
+2. **Runner** — main loop: finds pending node executions, resolves join conditions, executes ready nodes in parallel batches via `Concurrent::Promises.future`
+3. **NodeRunner** — executes a single node through its plugin, handles waiting status
+4. **Enqueue next** — after a node completes, creates pending `NodeExecution` records for downstream nodes based on edge routing
+5. **Finalize** — when no more pending nodes, marks execution as completed/failed and updates context status
+
+### Edge routing
+
+Edges can have a `source_handle` for conditional routing. When a node (e.g., Condition) outputs `{ result: "true" }`, only edges with a matching `source_handle` (or no handle) are followed.
+
+### Join semantics
+
+Nodes can have `conditions_json: { join: "all" }` or `{ join: "any" }`:
+- **join: all** — waits for all predecessor nodes to complete before executing
+- **join: any** — executes as soon as any predecessor completes
+
+### Wait/Resume
+
+Nodes can pause execution by setting their status to "waiting" (Wait node, HumanAction node). Resume with:
+
+```ruby
+# Direct resume
+Orkestr::ExecutionService::Complete.new(node_execution, output: { data: "value" }).call
+
+# Via job (async)
+Orkestr::ResumeExecutionJob.perform_later(execution.id, node_execution_id: ne.id, output: { data: "value" })
+```
+
+### Safety
+
+- **Cycle detection** — `WorkflowSynchronizer` runs DFS-based cycle detection on graph sync (disabled when `allow_cycles` is true; Runner MAX_ITERATIONS=1000 still guards against runaway loops)
+- **Max iterations** — Runner stops after 1000 iterations to prevent runaway loops
+- **Unique constraint** — `(execution_id, node_id)` unique index prevents duplicate node executions
+- **Query cache bypass** — Runner uses `ActiveRecord::Base.uncached` to avoid stale reads during concurrent execution
+
+## Database Schema
+
+All tables use UUID primary keys (`pgcrypto`). Tables are prefixed with `orkestr_`.
+
+| Table | Description |
+|---|---|
+| `orkestr_workflows` | Workflow definitions with graph, trigger config, defaults |
+| `orkestr_nodes` | Node records synced from graph_json |
+| `orkestr_edges` | Edge records synced from graph_json |
+| `orkestr_contexts` | Execution contexts (polymorphic, linked to workflow) |
+| `orkestr_executions` | Workflow execution instances |
+| `orkestr_node_executions` | Per-node execution state with I/O data |
+| `orkestr_human_tasks` | Human-in-the-loop tasks with form schema |
+| `orkestr_assignees` | Polymorphic task assignments with deadlines |
+| `orkestr_execution_logs` | Structured execution logs |
+
+## Scheduled Workflows
+
+For scheduled workflows, add a cron job that runs every minute:
+
+```bash
+* * * * * cd /path/to/app && bundle exec rake orkestr:check_scheduled
+```
+
+## Development
+
+```bash
+# Start the database
+./bin/dev_db start
+
+# Run the test suite (452 specs)
+bundle exec rspec
+
+# Run linter
+bin/rubocop
+```
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).