workflow-canvas

# Workflow Canvas

**Purpose:** Implement Celery canvas patterns for composing complex, distributed task workflows.

**Activation Triggers:**
- Sequential task execution needed (chains)
- Parallel task processing required (groups)
- Synchronization after parallel work (chords)
- Complex workflow composition
- Task result aggregation
- Error handling in workflows
- Nested or conditional workflows

**Key Resources:**
- `scripts/test-workflow.sh` - Test workflow execution and validate patterns
- `scripts/validate-canvas.sh` - Validate canvas structure and dependencies
- `scripts/generate-workflow.sh` - Generate workflows from templates
- `templates/` - Complete workflow pattern implementations
- `examples/` - Real-world workflow scenarios with explanations

## Canvas Primitives

### 1. Signatures

Foundation of canvas system - encapsulate task invocation details:

```python
from celery import signature

# Named signature
signature('tasks.add', args=(2, 2), countdown=10)

# Using task method
add.signature((2, 2), countdown=10)

# Shortcut syntax (most common)
add.s(2, 2)

# Immutable signature (prevents result forwarding)
add.si(2, 2)
```

**Use templates/chain-workflow.py** for signature examples.

### 2. Chains

Sequential task execution where each task's result becomes next task's first argument:

```python
from celery import chain

# Explicit chain
chain(add.s(2, 2), add.s(4), add.s(8))()

# Pipe syntax (recommended)
(add.s(2, 2) | add.s(4) | add.s(8))()

# With immutable tasks (independent execution)
(add.si(2, 2) | process.s() | notify.si('done'))()
```

**Key Pattern:** Use `.si()` when task should NOT receive previous result.

**See templates/chain-workflow.py** for complete patterns.

### 3. Groups

Execute multiple tasks in parallel, returns GroupResult:

```python
from celery import group

# Parallel execution
group(add.s(i, i) for i in range(10))()

# With result tracking
job = group(process.s(item) for item in batch)
result = job.apply_async()
result.get()