# Punkit Creative — Enterprise Lead Nurture Sequence (V2)
## Developer Handover & Implementation Guide

This document outlines the architecture, data flow, and deployment steps for the **Enterprise Upgrade of Automation 4**. This version includes Clearbit Company Enrichment, HubSpot CRM syncing, Behavioral Branching, and Smart Reply Interception.

---

## 1. System Architecture Overview

*   **Frontend (Trigger Demo):** A minimalist landing page (`lead_nurture_demo.html`). To showcase the enrichment capabilities, it only asks for the lead's Name and Work Email.
*   **Workflow A: Main Sequence (`lead_nurture_workflow_v2.json`):** Handles company enrichment, CRM contact creation, AI email generation, and the 14-day execution drip with conditional branching (checking HubSpot for replies before sending the next email).
*   **Workflow B: Reply Listener (`lead_reply_listener.json`):** A standalone workflow that constantly monitors Gmail for replies to the AI sequence. If a reply is caught, it updates the HubSpot contact status and sends a Slack alert to the team.

### The Data Flow
1. Lead submits Name & Email.
2. **Main Workflow** triggers. The `Clearbit` mock node enriches the email domain to find the company and industry.
3. The `HubSpot` node creates a new Contact with the enriched data.
4. The `Groq` API generates 5 hyper-personalized emails using the enriched data.
5. Email 1 is sent and logged to HubSpot. 
6. The workflow pauses at a Wait node.
7. If the lead replies in the meantime, the **Reply Listener Workflow** catches it, updates the HubSpot `lead_status` to "Replied", and sends a Slack alert.
8. When the Wait node finishes, the Main Workflow checks HubSpot. If `lead_status == "Replied"`, it sends a "Hot Lead" Slack alert and terminates the drip. If not, it sends Email 2.

---

## 2. Implementation Steps

### Phase 1: Deploying the Workflows
1. Import **both** JSON files into your n8n instance.
2. **Authenticate Groq:** In the Main Workflow, add your Groq API Key to the "Groq API" node.
3. **Authenticate HubSpot (CRITICAL):**
   * Both workflows contain `HubSpot` nodes. You must authenticate them via OAuth2 or Private App Token.
   * *Note:* Ensure your HubSpot instance has a property called `lead_status` (this is standard in HubSpot) with a dropdown option exactly matching "Replied".
4. **Authenticate Slack:** Connect the Slack nodes to your agency's actual workspace and select the desired channel (e.g., `#sales-alerts`).
5. **Authenticate Clearbit:** The "Clearbit" node is an HTTP Request mock. For production, add your Clearbit API key as a Bearer token in the headers, or replace it with the official n8n Clearbit node.

### Phase 2: Configuring Email & Wait Nodes
1. **Gmail Authentication:** Authenticate the `Send Email` nodes in the Main Workflow, and the `Gmail Trigger` node in the Reply Listener.
2. **Wait Nodes (CRITICAL):**
   * *Demo Mode:* The Wait nodes are currently set to 1–4 **minutes**.
   * *Production Mode:* Change all Wait nodes to `days` (e.g., Wait 1 = 2 Days, Wait 2 = 3 Days) to achieve the 14-day drip.

---

## 3. Required Dependencies
*   **n8n instance** (Must support long-running Wait nodes).
*   **Groq API Key** (LLaMA 3.3).
*   **HubSpot Account** (Free or Paid).
*   **Clearbit API Key** (or Apollo/ZoomInfo).
*   **Slack Workspace**.
*   **Google Workspace Credentials** (OAuth2).