N8N Integration

N8N is used as the workflow orchestration engine for document processing, AI extraction, and embedding generation.

Architecture

sequenceDiagram
    participant App as PIP AI Server
    participant N8N as N8N Workflow
    participant AI as OpenAI / LLM
    participant DB as Supabase DB
    participant Store as Supabase Storage

    App->>N8N: Webhook trigger (with secret)
    N8N->>Store: Download document (signed URL)
    N8N->>AI: OCR / Extract / Embed
    N8N->>DB: Upsert structured data
    N8N->>App: Callback (status + results)

Workflows

1. Spec Processing

Trigger: POST {N8N_BASE_URL}/webhook/pip-ai-spec-upsert

Payload:

{
  "spec_upload_id": "uuid",
  "document_id": "uuid",
  "storage_path": "specs/brand/upload_id/file.pdf",
  "brand_name": "Holiday Inn Express",
  "area": "guest-room",
  "property_name": "San Francisco Airport",
  "job_id": "uuid"
}

Steps:

1. Download spec PDF via signed URL
2. OCR/LLM extraction → structured sections
3. Upsert pip_ai_spec_sections with unique (spec_upload_id, spec_number)
4. Generate embeddings via OpenAI text-embedding-3-small
5. Update processing status
6. Callback to app

2. PIP Processing

Trigger: POST {N8N_BASE_URL}/webhook/pip-ai-pip-processor

Payload:

{
  "document_id": "uuid",
  "project_id": "uuid",
  "storage_path": "pips/project_id/doc_id/file.pdf",
  "job_id": "uuid"
}

Steps:

1. Download PIP PDF
2. OCR/LLM extraction → structured line items
3. Upsert pip_ai_pip_items with unique (project_id, code)
4. For each item, query pip_ai_search_specs() (filtered by brand + areas)
5. Insert candidate matches into pip_ai_matches
6. Update processing status
7. Callback to app

3. Floor Plan Processing

Trigger: POST {N8N_BASE_URL}/webhook/pip-ai-floor-plan-processor

Steps:

1. Download floor plan
2. Render to PNG + generate thumbnail
3. OCR visible labels → extract spec codes
4. Update pip_ai_floor_plans.extracted_spec_codes[]
5. Link to known spec sections
6. Callback to app

4. PDF Export

Handles document builder PDF generation.

5. AI Image Generation (Nano Banana)

See Nano Banana integration.

Webhook Security

All webhooks use a shared secret for authentication:

Header: x-webhook-secret: <N8N_WEBHOOK_SECRET>

Job Queue Pattern

N8N can also poll the pip_ai_upload_jobs table:

-- Claim a job
UPDATE pip_ai_upload_jobs
SET status = 'processing', locked_at = now(), locked_by = 'n8n-worker'
WHERE id = '<job_id>' AND status = 'queued'
RETURNING *;

Idempotency

All N8N workflows are designed to be safely re-runnable:

• Upserts use unique constraints
• Job status tracking prevents double-processing
• retry_count tracks reprocessing attempts

Configuration

N8N_BASE_URL=https://your-n8n-instance.com
N8N_WEBHOOK_SPEC_PROCESSOR=/webhook/pip-ai-spec-upsert
N8N_WEBHOOK_PIP_PROCESSOR=/webhook/pip-ai-pip-processor
N8N_WEBHOOK_FLOOR_PLAN_PROCESSOR=/webhook/pip-ai-floor-plan-processor
N8N_WEBHOOK_SECRET=your-shared-secret