File size: 6,005 Bytes
dd480ef | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 | /**
* Workflow Patterns Knowledge Base
* Production-grade patterns for senior-level workflow engineering
* Used by Planner and Compiler to apply best practices
*/
export const WORKFLOW_PATTERNS = {
// ─── Retry Patterns ────────────────────────────────────────────────────────
retry: {
exponentialBackoff: {
name: 'Exponential Backoff Retry',
description: 'Retries with increasing delay to avoid overwhelming services',
n8nConfig: { retryOnFail: true, maxTries: 3, waitBetweenTries: 1000 },
useWhen: 'External API calls, LLM requests, database writes',
},
linearRetry: {
name: 'Linear Retry',
description: 'Fixed delay retries for idempotent operations',
n8nConfig: { retryOnFail: true, maxTries: 5, waitBetweenTries: 2000 },
useWhen: 'File operations, simple CRUD, idempotent webhooks',
},
},
// ─── Webhook Safety Patterns ──────────────────────────────────────────────
webhookSafety: {
validateAndEnqueue: {
name: 'Validate → Enqueue → Acknowledge',
description: 'Webhook receives, validates, enqueues for async processing, returns 200 quickly',
steps: ['Webhook Trigger', 'Validate Signature', 'Validate Schema', 'Generate Idempotency Key', 'Check Processed', 'Enqueue Job', 'Return 200'],
avoids: 'Webhook timeout, duplicate processing, heavy sync processing',
},
idempotencyGuard: {
name: 'Idempotency Guard',
description: 'Prevents duplicate processing using request fingerprinting',
steps: ['Hash request body+timestamp', 'Check KV/DB for existing hash', 'Skip if already processed', 'Store hash after processing'],
},
},
// ─── AI Workflow Patterns ─────────────────────────────────────────────────
aiWorkflow: {
validateAiOutput: {
name: 'AI Output Validation',
description: 'Validates AI output schema before using downstream',
steps: ['Call LLM', 'Check output is valid JSON', 'Validate against expected schema', 'Retry with different prompt if invalid', 'Fallback to safe default if all retries fail'],
},
moderationGate: {
name: 'Content Moderation Gate',
description: 'Moderate AI output before sending to users',
steps: ['AI generates content', 'Run moderation API', 'Block if flagged', 'Log moderation events', 'Allow if safe'],
},
},
// ─── Error Handling Patterns ──────────────────────────────────────────────
errorHandling: {
deadLetterQueue: {
name: 'Dead Letter Queue',
description: 'Failed items are stored for manual review/reprocessing',
steps: ['Process item', 'On max retry exhaustion', 'Write to DLQ table/sheet', 'Alert on-call via notification', 'Dashboard shows DLQ items'],
},
circuitBreaker: {
name: 'Circuit Breaker',
description: 'Stop hammering a failing service after threshold',
steps: ['Track failure count in KV', 'If count > threshold → open circuit', 'Return cached response or fallback', 'Probe service after timeout → half-open', 'Reset on success'],
},
},
// ─── Observability Patterns ───────────────────────────────────────────────
observability: {
structuredLogging: {
name: 'Structured Logging',
description: 'Every significant action logs jobId, nodeId, timestamp, status',
implementation: 'Code node at monitoring layer outputs structured log JSON to webhook/external log service',
},
executionNotification: {
name: 'Execution Completion Notification',
description: 'Notify on workflow success/failure',
steps: ['After final node', 'Compose summary message', 'Send to Slack/Telegram channel'],
},
},
// ─── Approval Patterns ────────────────────────────────────────────────────
approval: {
humanApproval: {
name: 'Human-In-The-Loop Approval',
description: 'Pause workflow and wait for human decision',
steps: ['Generate approval request', 'Send notification with approve/reject link', 'Wait for webhook callback', 'Route based on decision'],
},
},
// ─── Anti-Patterns ────────────────────────────────────────────────────────
antiPatterns: [
{
name: 'Monolithic Workflow',
description: '200+ nodes in one workflow with no separation of concerns',
fix: 'Split into subworkflows by responsibility domain',
},
{
name: 'Silent Failure',
description: 'Workflow fails without any notification or logging',
fix: 'Add error notification nodes and error workflow setting',
},
{
name: 'Direct Webhook Processing',
description: 'Heavy processing inside webhook request path causing timeouts',
fix: 'Use validate → enqueue → acknowledge pattern',
},
{
name: 'Unsafe AI Trust',
description: 'Using AI output directly without validation',
fix: 'Always validate AI output schema before downstream use',
},
{
name: 'Credential Hardcoding',
description: 'API keys in Code nodes or Set node values',
fix: 'Always use n8n credential system',
},
{
name: 'No Retry Policy',
description: 'External API calls without retry configuration',
fix: 'Add retryOnFail: true to all external API nodes',
},
],
};
|