// Input/output format for all nodes
[
  {
    json: { /* Your data object */ },
    binary: { /* Optional binary data (files, images) */ },
    pairedItem: { /* Reference to source item */ }
  }
]

[Trigger] → [Validation] → [Branch (If/Switch)] → [Processing] → [Error Handler]
                                ↓                      ↓
                          [Path A nodes]        [Path B nodes]
                                ↓                      ↓
                          [Merge/Output]         [Output]

// Access input items
const items = $input.all();

// Process data
const processedItems = items.map(item => {
  const inputData = item.json;

  return {
    json: {
      // Output fields
      processed: inputData.field.toUpperCase(),
      timestamp: new Date().toISOString()
    }
  };
});

// Return transformed items
return processedItems;

const items = $input.all();
return items.filter(item => item.json.status === 'active');

const items = $input.all();
const grouped = _.groupBy(items, item => item.json.category);

return [{
  json: {
    summary: Object.keys(grouped).map(category => ({
      category,
      count: grouped[category].length
    }))
  }
}];

const items = $input.all();
const results = [];

for (const item of items) {
  const response = await fetch(`https://api.example.com/data/${item.json.id}`);
  const data = await response.json();

  results.push({
    json: {
      original: item.json,
      enriched: data
    }
  });
}

return results;

const items = $input.all();

return items.map(item => {
  try {
    // Risky operation
    const result = JSON.parse(item.json.data);
    return { json: { parsed: result } };
  } catch (error) {
    return {
      json: {
        error: error.message,
        original: item.json.data
      }
    };
  }
});

undefined

processed_items.append({
    'json': {
        'processed': input_data['field'].upper(),
        'timestamp': datetime.now().isoformat()
    }
})

**Complexity Rating: Code Nodes**
- Simple transformations (map/filter): **1**
- API calls with error handling: **2**
- Multi-step async operations: **3**
- Complex algorithms with libraries: **4**
- Performance-critical processing: **5** (consider custom node)

undefined

**Step 2: Implement Logic**
- Define node properties (parameters, credentials)
- Implement execute method
- Add error handling
- Write unit tests (optional)

**Step 3: Build and Test**
```bash

**Step 4: Publish**
```bash

**Complexity Rating: Custom Nodes**
- Declarative CRUD wrapper: **2**
- Programmatic with authentication: **3**
- Complex state management: **4**
- Advanced polling/webhooks: **5**

Has native node? ──Yes──> Use native node
     │
     No
     ├──> Simple REST API? ──Yes──> HTTP Request node
     ├──> Complex auth (OAuth2)? ──Yes──> Build custom node
     ├──> Reusable across workflows? ──Yes──> Build custom node
     └──> One-off integration? ──Yes──> Code node with fetch()

URL: https://api.example.com/users
Method: GET
Query Parameters:
  - status: active
  - limit: 100
Authentication: Header Auth
  - Name: Authorization
  - Value: Bearer {{$credentials.apiKey}}

URL: https://api.example.com/users
Method: POST
Body Content Type: JSON
Body:
{
  "name": "={{ $json.name }}",
  "email": "={{ $json.email }}"
}

let allResults = [];
let page = 1;
let hasMore = true;

while (hasMore) {
  const response = await this.helpers.request({
    method: 'GET',
    url: `https://api.example.com/data?page=${page}`,
    json: true,
  });

  allResults = allResults.concat(response.results);
  hasMore = response.hasNext;
  page++;
}

return allResults.map(item => ({ json: item }));

// In Code node after webhook trigger
const webhookData = $input.first().json;

// Process data
const result = processData(webhookData);

// Return response (synchronous webhook)
return [{
  json: {
    status: 'success',
    data: result
  }
}];

Production: https://your-domain.com/webhook/workflow-id
Test: https://your-domain.com/webhook-test/workflow-id

-- PostgreSQL node
SELECT * FROM users
WHERE created_at > $1
  AND status = $2
ORDER BY created_at DESC

-- Parameters from previous node
Parameters: ['{{ $json.startDate }}', 'active']

// Code node preparing data for database
const items = $input.all();
const values = items.map(item => ({
  name: item.json.name,
  email: item.json.email,
  created_at: new Date().toISOString()
}));

return [{ json: { values } }];

// Next node: PostgreSQL
// INSERT INTO users (name, email, created_at)
// VALUES {{ $json.values }}

Workflow: File Trigger → S3 Upload
- File Trigger: Monitor directory for new files
- S3 node:
  - Operation: Upload
  - Bucket: my-bucket
  - File Name: {{ $json.fileName }}
  - Binary Data: true (from file trigger)

HTTP Request (download) → Code (process) → Google Drive (upload)
- HTTP Request: Binary response enabled
- Code: Process $binary.data
- Google Drive: Upload with binary data

Manual Trigger → AI Agent → Output
- AI Agent:
  - Prompt: "You are a helpful assistant that {{$json.task}}"
  - Tools: [Calculator, HTTP Request]
  - Memory: Conversation Buffer Window

Webhook → AI Agent → If (requires approval) → Send Email → Wait for Webhook → Execute Action
                            ↓ (auto-approve)
                        Execute Action

Loop Start → AI Agent → Tool Execution → State Update → Loop End (condition check)
     ↑______________________________________________________________|

// Code node - Initialize state
return [{
  json: {
    task: 'Research topic',
    iteration: 0,
    maxIterations: 5,
    context: [],
    completed: false
  }
}];

// Code node - Update state
const state = $json;
state.iteration++;
state.context.push($('AI Agent').item.json.response);
state.completed = state.iteration >= state.maxIterations || checkGoalMet(state);

return [{ json: state }];

Query Input → Vector Store Search → Format Context → LLM → Response Output

npm install n8n -g
n8n start

**Environment Configuration:**

[See: Complete environment variable reference in examples/n8n_deployment.yaml]

Essential variables:
- `N8N_HOST` - Public URL for webhooks
- `WEBHOOK_URL` - Webhook endpoint base
- `N8N_ENCRYPTION_KEY` - Credential encryption (must persist)
- `DB_TYPE` - Database (SQLite/PostgreSQL/MySQL/MariaDB)
- `EXECUTIONS_DATA_SAVE_ON_ERROR` - Error logging
- `EXECUTIONS_DATA_SAVE_ON_SUCCESS` - Success logging

Performance tuning variables documented in examples/n8n_deployment.yaml

undefined

**Database:**
- SQLite: Development/low volume (<1000 executions/day)
- PostgreSQL: Production (recommended)
- MySQL/MariaDB: Alternative for existing infrastructure

**Resource Requirements:**

| Workflow Volume | CPU | RAM | Database |
|----------------|-----|-----|----------|
| <100 exec/day | 1 core | 512MB | SQLite |
| 100-1000/day | 2 cores | 2GB | PostgreSQL |
| 1000-10000/day | 4 cores | 4GB | PostgreSQL |
| >10000/day | 8+ cores | 8GB+ | PostgreSQL + Queue mode |

**Monitoring:**
- Enable execution logs (EXECUTIONS_DATA_SAVE_*)
- Set up error workflows (Error Trigger node)
- Monitor database size (execution history cleanup)
- Track webhook response times

// Always validate input structure
const items = $input.all();

for (const item of items) {
  if (!item.json.email || !item.json.name) {
    throw new Error(`Invalid input: missing required fields at item ${item.json.id}`);
  }
}

// Provide debugging information
try {
  const result = await apiCall(item.json.id);
} catch (error) {
  throw new Error(`API call failed for ID ${item.json.id}: ${error.message}`);
}

// Check existence before creation
const exists = await checkExists(item.json.uniqueId);
if (!exists) {
  await createRecord(item.json);
}

Schedule Trigger (hourly) → Fetch Source Data → Transform → If (record exists) → Update Target
                                                                    ↓ (new)
                                                                Create in Target

Main Workflow → Process → Error → Error Trigger Workflow
                                        ↓
                                   Wait (delay) → Retry → If (max retries) → Alert

Webhook → Split In Batches → For Each Item:
                                  ↓
                             API Call (enrich) → Code (merge) → Batch Results
                                                                      ↓
                                                                Database Insert

SQS Trigger → Parse Message → Switch (event type) → [Handler A, Handler B, Handler C] → Confirm/Delete Message

Trigger → Generate Request → Send Email (approval link) → Webhook (approval response) → If (approved) → Execute Action
                                                                                              ↓ (rejected)
                                                                                         Send Rejection Notice

Schedule → Extract (API) → Validate → Transform → Load (Database) → Success Notification
                               ↓                                            ↓
                          Error Handler ────────────────────> Error Notification

// Log intermediate values
const data = $json;
console.log('Debug data:', JSON.stringify(data, null, 2));
return [{ json: data }];

// Expression to check data quality
{{ $json.email && $json.email.includes('@') }}