Skip to content

Workflow.md

Latest commit

 

History

History
96 lines (74 loc) · 4.41 KB

Workflow.md

File metadata and controls

96 lines (74 loc) · 4.41 KB
Raw

🔄 LeadIQ-AI — Workflow Architecture & Node Pipeline Guide

Pipeline Version: v2
Orchestration Engine: n8n
State Engine: Supabase PostgreSQL (reserve_lead_v1, complete_lead_v1)

1. Pipeline Lifecycle Overview

LeadIQ-AI executes an event-driven, synchronous pipeline from inbound webhook reception to multi-channel dispatch.

flowchart TD
    A[POST /webhook/leadiq] --> Auth[X-Webhook-Secret Gate]
    Auth --> B[Validate and Normalise Lead]
    B --> C[Supabase Reservation RPC reserve_lead_v1]
    C -->|Outcome: OWNER| D[Gemini AI Scoring Node]
    C -->|Outcome: DUPLICATE_COMPLETED| E[Reuse Cached Qualification]
    C -->|Outcome: DUPLICATE_IN_FLIGHT| F[Wait / Return Processing Status]
    
    D --> G[Supabase Complete RPC complete_lead_v1]
    G --> H[Google Sheets Logger Node]
    E --> H
    
    H --> I{Tier Routing Switch}
    I -->|HOT| J[Slack Alert #sales-hot]
    J --> K[Skip Gmail per existing HOT policy]
    I -->|WARM| L[Gmail Follow-up Email]
    I -->|COLD| M[End Workflow]
    K --> N[200 OK Response]
    L --> N
    M --> N
Loading

2. Step-by-Step Node Execution Breakdown

Node 1: Webhook — Lead Submission

  • Type: n8n Webhook Node (/webhook/lead-qualification)
  • Method: POST
  • Purpose: Ingestion endpoint for web forms, CRMs, or landing pages.
  • Payload Schema: Requires canonical fields (name, email, company, message, phone, country, source).

Node 2: Data Normaliser

  • Type: n8n Code / Function Node
  • Purpose: Normalizes email addresses (lowercasing, trimming spaces), generates correlation IDs (request_id, lead_id), standardizes empty fields to nulls, and sets default timestamps.

Node 3: Supabase — Reserve Lead RPC

  • Type: n8n HTTP Request Node
  • Endpoint: ${SUPABASE_URL}/rest/v1/rpc/reserve_lead_v1
  • Purpose: Acquires database lock and evaluates the 10-minute duplicate window using transactional PostgreSQL logic.
  • Return Statuses:
    • OWNER: First-time submission. Proceeds to Gemini AI scoring.
    • DUPLICATE_COMPLETED: Previously scored within 10 minutes. Bypasses Gemini call and reuses existing AI result.
    • DUPLICATE_IN_FLIGHT: Currently processing by another worker.

Node 4: Gemini AI — Scoring & Tiering

  • Type: n8n HTTP Request Node
  • Model: gemini-2.5-flash
  • Prompt: Evaluates lead against B2B Ideal Customer Profile (ICP), urgency, budget, and seniority.
  • Output JSON: Returns structured score (0–100), tier (HOT, WARM, COLD), and plain text reasoning.

Node 5: Supabase — Complete Lead RPC

  • Type: n8n HTTP Request Node
  • Endpoint: ${SUPABASE_URL}/rest/v1/rpc/complete_lead_v1
  • Purpose: Persists validated Gemini scoring output into Supabase and updates reservation state to completed.

Node 6: Sheets — Append Lead Record

  • Type: n8n Google Sheets Node
  • Purpose: Appends complete lead row to Google Sheets audit log (Leads tab) regardless of tier.

Node 7: Routing Switch — Lead Tier

  • Type: n8n Switch / IF Node
  • Branching Rules:
    • HOT: Leads scoring 80+ or enterprise intent. Triggers Slack #sales-hot; the existing v2 policy skips Gmail.
    • WARM: Leads scoring 50–79. Triggers Gmail nurture response.
    • COLD: Leads scoring < 50. Saved to Google Sheets only; no active alerts.

Node 8 & 9: Slack Alert & Gmail Sender

  • Slack Node: Posts real-time Markdown block with lead contact details, score, and AI reasoning to #sales-hot.
  • Gmail Node: Sends a personalized email acknowledgement to the lead's email address.

3. Error Handling & Recovery

  • Lease Expiry: If a worker crashes mid-execution, the processing lease expires after 15 minutes, marking the record RECOVERY_REQUIRED.
  • Downstream Failure Isolation: Downstream integration status (Slack, Sheets, Gmail) is recorded independently via mark_integration_status_v1. A failed notification can be retried without re-running Gemini AI scoring.

v2 Runtime Hardening

  • Production requests require X-Webhook-Secret; other environments are controlled by N8N_WEBHOOK_AUTH_REQUIRED.
  • Gemini and reservation/status reads use bounded retries. Sheets, Slack, Gmail, and state-changing Supabase calls use bounded timeouts and do not automatically replay unsafe creates.
  • GET /webhook/leadiq-health reports configuration readiness and returns HTTP 503 when required configuration is missing.