# Data Flow Diagrams

**Last Updated:** 2026-01-10

Visual representation of data flows for all form submission types and lead capture workflows.

## Overview

This document provides mermaid diagrams showing how data flows through the system for:

- Tools/calculator form submissions
- Template download forms
- Lead capture popup (two-step)
- Webinar registrations
- ShiftOps report unlock

## Tools/Calculator Form Flow

```mermaid
flowchart TD
    A[User fills calculator] --> B[User clicks Export/Email]
    B --> C{Email modal shown?}
    C -->|No| D[Show email modal]
    C -->|Yes| E[User enters email]
    D --> E
    E --> F[Frontend: Collect UTM data]
    F --> G[Frontend: Validate email]
    G --> H[Frontend: POST /v2/api/collect-lead.php]
    H --> I[Backend: Validate input]
    I --> J[Backend: Extract hubspotutk cookie]
    J --> K[Backend: Prepare HubSpot payload]
    K --> L[Backend: Submit to Forms API v3]
    L --> M{Success?}
    M -->|Yes| N[HubSpot: Create contact]
    M -->|No| O[Retry logic 3x]
    O --> L
    N --> P[Backend: Track page view Events API]
    P --> Q[Backend: Send welcome email]
    Q --> R[Frontend: Show success]
    R --> S[Frontend: Unlock content/download]
```

## Template Download Form Flow

```mermaid
flowchart TD
    A[User visits template page] --> B[User clicks Download]
    B --> C[Show HubSpot form modal]
    C --> D[User fills form]
    D --> E[Frontend: Collect UTM data]
    E --> F[Frontend: POST /v2/api/submit-template.php]
    F --> G[Backend: Validate input]
    G --> H[Backend: Extract hubspotutk cookie]
    H --> I[Backend: Detect template type]
    I --> J[Backend: Prepare HubSpot payload]
    J --> K[Backend: Submit to Forms API v3]
    K --> L{Success?}
    L -->|Yes| M[HubSpot: Create contact]
    L -->|No| N[Retry logic 3x]
    N --> K
    M --> O[Backend: Return success]
    O --> P[Frontend: Show success]
    P --> Q[Frontend: Trigger download]
```

## Lead Capture Popup Flow (Two-Step)

```mermaid
flowchart TD
    A[Page loads] --> B[Trigger system active]
    B --> C{Trigger condition met?}
    C -->|Time/Scroll/Exit| D[Show Step 1 popup]
    C -->|No| B
    D --> E[User enters name + phone]
    E --> F[Frontend: Validate input]
    F --> G[Frontend: POST /v2/api/lead-capture.php Step 1]
    G --> H[Backend: Generate lead ID]
    H --> I[Backend: Create temp email]
    I --> J[Backend: Submit to Forms API v3]
    J --> K[HubSpot: Create contact with temp email]
    K --> L[Backend: Append to Google Sheets]
    L --> M[Backend: Return lead ID]
    M --> N[Frontend: Show Step 2]
    N --> O[User enters email + notes]
    O --> P[Frontend: POST /v2/api/lead-capture.php Step 2]
    P --> Q[Backend: Find contact by temp email]
    Q --> R[Backend: Update via CRM API]
    R --> S[Backend: Update Google Sheets]
    S --> T[Backend: Submit to Forms API v3 for activity]
    T --> U[Frontend: Show success]
```

## Webinar Registration Flow

```mermaid
flowchart TD
    A[User visits webinar page] --> B[User selects date]
    B --> C[User fills registration form]
    C --> D[Frontend: Collect UTM data]
    D --> E[Frontend: POST /v2/api/webinar-registration.php]
    E --> F[Backend: Validate input]
    F --> G[Backend: Extract hubspotutk cookie]
    G --> H[Backend: Track page view Events API]
    H --> I[Backend: Create contact CRM API v3]
    I --> J{Success?}
    J -->|Yes| K[Backend: Track page view Events API]
    J -->|No| L[Retry logic 3x]
    L --> I
    K --> M[Backend: Append to Google Sheets]
    M --> N[Backend: Send confirmation email]
    N --> O[Frontend: Show success]
```

## ShiftOps Report Unlock Flow

```mermaid
flowchart TD
    A[User completes ShiftOps quiz] --> B[User views report]
    B --> C[Report locked - show unlock form]
    C --> D[User fills form]
    D --> E[Frontend: Collect UTM data]
    E --> F[Frontend: POST /v2/api/shiftops-hubspot.php]
    F --> G[Backend: Check rate limit]
    G --> H{Rate limit OK?}
    H -->|No| I[Return 429 error]
    H -->|Yes| J[Backend: Validate input]
    J --> K[Backend: Extract hubspotutk cookie]
    K --> L[Backend: Prepare HubSpot payload]
    L --> M[Backend: Submit to Forms API v3 Public]
    M --> N{Success?}
    N -->|Yes| O[HubSpot: Create contact]
    N -->|No| P[Retry logic 3x]
    P --> M
    O --> Q[Backend: Return success]
    Q --> R[Frontend: Unlock report]
```

## UTM Data Collection Flow

```mermaid
flowchart TD
    A[Page loads] --> B[UTM Tracker initializes]
    B --> C[Extract UTM from URL]
    C --> D{UTM in URL?}
    D -->|Yes| E[Store in cookies 30 days]
    D -->|No| F[Check cookies]
    F --> G{UTM in cookies?}
    G -->|Yes| H[Use cookie values]
    G -->|No| I[Detect from referrer]
    E --> J[Apply Google Ads corrections]
    H --> J
    I --> J
    J --> K[Detect lead source]
    K --> L[Store in window.utmTracker]
    L --> M[Form submission]
    M --> N[getUTMDataForAPI called]
    N --> O[Return UTM object]
    O --> P[Include in API request]
```

## HubSpot Forms API v3 Submission Flow

```mermaid
flowchart TD
    A[API endpoint receives request] --> B[Extract hubspotutk]
    B --> C{Cookie exists?}
    C -->|Yes| D[Use cookie value]
    C -->|No| E[Use request body]
    D --> F[Prepare Forms API payload]
    E --> F
    F --> G[Add fields array]
    G --> H[Add context object]
    H --> I[Include hutk in context]
    I --> J[Include pageUri in context]
    J --> K[Include pageName in context]
    K --> L[POST to Forms API v3]
    L --> M{HTTP 200/204?}
    M -->|Yes| N[Extract contact ID]
    M -->|No| O{Retryable error?}
    O -->|Yes| P[Wait + retry]
    O -->|No| Q[Return error]
    P --> L
    N --> R[Track page view Events API]
    R --> S[Return success]
```

## Lead Source Detection Flow

```mermaid
flowchart TD
    A[UTM data available] --> B{Has gclid?}
    B -->|Yes| C[Google Ads traffic]
    C --> D[utm_source: adwords]
    D --> E[utm_medium: ppc]
    E --> F[leadSource: Paid Search/Google]
    B -->|No| G{Has utm_source?}
    G -->|Yes| H{Source type?}
    G -->|No| I[Check referrer]
    H -->|google + organic| J[leadSource: Organic Search]
    H -->|fb/facebook + paid| K[leadSource: meta]
    H -->|linkedin| L[leadSource: linkedin]
    H -->|Domain pattern| M[leadSource: referral]
    I --> N{Referrer domain?}
    N -->|Known AI tool| M
    N -->|Google| J
    N -->|None| O[leadSource: Direct Traffic]
    F --> P[Final lead source]
    J --> P
    K --> P
    L --> P
    M --> P
    O --> P
```

## Related Documentation

- [Form-to-Page Mapping](FORM_TO_PAGE_MAPPING.md) - Which forms are used where
- [Form Configuration Reference](FORM_CONFIGURATION_REFERENCE.md) - Field mappings
- [HubSpot API Reference](../apis/HUBSPOT_API_REFERENCE.md) - Complete API documentation