knowledge/workflow-patterns/index.ts

/**
 * 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',
    },
  ],
};