chorus-services/planning and reports/LEAD_CAPTURE_SYSTEM.md

CHORUS Lead Capture System

A comprehensive, internationally-compliant lead capture system with GDPR compliance, security features, and seamless integration with the CHORUS website.

Features

🔒 Security & Compliance

• Rate Limiting: IP-based and email-based rate limiting to prevent spam
• Input Validation: Comprehensive server-side validation using Zod schemas
• SQL Injection Protection: Parameterized queries with PostgreSQL
• XSS Prevention: Input sanitization using validator library
• GDPR Compliance: Full consent management and audit trails
• Honeypot Detection: Basic bot detection mechanism

🌍 International Support

• Phone Validation: International phone number validation using libphonenumber-js
• Country Detection: Automatic country detection from timezone
• Address Formats: Flexible address fields supporting international formats
• Multi-language Ready: Form structure ready for internationalization

📧 Automated Notifications

• Email Notifications: Instant notifications for new leads
• Lead Classification: Automatic categorization by lead source
• Formatted Reports: Structured email reports with all lead details

🎨 User Experience

• Ultra-Minimalist Design: Consistent with CHORUS brand aesthetic - clean, no border radius
• Dark Mode Default: Professional dark theme with light mode toggle
• 8-Color Accessibility: Vision inclusive design for protanopia, deuteranopia, tritanopia, achromatopsia
• Three.js Integration: Möbius ring logo with accessibility-aware animations
• Typography Hierarchy: Inter Tight for forms, Exo Thin for brand elements
• Progressive Forms: Different fields shown based on lead source type
• Real-time Validation: Client-side validation with server-side verification
• Sophisticated States: Elegant success confirmations with brand-consistent motion

Architecture

Database Schema

-- Core leads table with international support
leads (
  id UUID PRIMARY KEY,
  first_name, last_name, email, phone,
  company information,
  address information (international),
  lead source & status,
  GDPR compliance fields,
  UTM tracking,
  audit timestamps
)

-- GDPR compliance audit trail
consent_audit (
  id UUID PRIMARY KEY,
  lead_id UUID REFERENCES leads(id),
  consent_type, consent_status, consent_date,
  audit trail information
)

-- Lead interaction tracking
lead_interactions (
  id UUID PRIMARY KEY,
  lead_id UUID REFERENCES leads(id),
  interaction details,
  next actions
)

-- Rate limiting protection
rate_limits (
  id UUID PRIMARY KEY,
  identifier, action_type,
  attempt tracking
)

API Endpoints

POST /api/leads

Submit a new lead capture form.

Request Body:

{
  "firstName": "John",
  "lastName": "Doe",
  "email": "john@example.com",
  "leadSource": "schedule_strategic_demo",
  "phone": "+1234567890",
  "countryCode": "US",
  "companyName": "Example Corp",
  "companyRole": "CTO",
  "companySize": "enterprise",
  "companyIndustry": "Technology / Software",
  "inquiryDetails": "Looking for AI orchestration solutions",
  "customMessage": "Additional context...",
  "gdprConsent": true,
  "marketingConsent": false
}

Response:

{
  "success": true,
  "message": "Lead captured successfully",
  "leadId": "550e8400-e29b-41d4-a716-446655440000"
}

GET /api/leads

Retrieve lead statistics (authenticated).

Headers:

Authorization: Bearer your-api-key

Response:

{
  "success": true,
  "stats": [
    {
      "lead_source": "schedule_strategic_demo",
      "total_leads": 45,
      "leads_last_30_days": 12,
      "leads_last_7_days": 3,
      "converted_leads": 8
    }
  ],
  "totalLeads": 156
}

Lead Sources Configuration

const LEAD_FORM_CONFIGS: Record<LeadSourceType, LeadFormConfig> = {
  schedule_strategic_demo: {
    title: 'Schedule Your Strategic Demo',
    subtitle: 'Experience Business-Intelligent AI Orchestration',
    showFields: { phone: true, company: true, customMessage: true },
    submitButtonText: 'Schedule Demo'
  },
  technical_deep_dive: {
    title: 'Technical Deep Dive',
    subtitle: 'Architecture Overview for Engineering Teams',
    showFields: { phone: false, company: true, customMessage: true },
    submitButtonText: 'Get Technical Details'
  },
  // ... other configurations
};

Setup Instructions

1. Database Setup

# Create database and run schema
createdb chorus
psql chorus < database/schema.sql

2. Environment Variables

Copy .env.example to .env.local and configure:

# Database
DATABASE_URL="postgresql://chorus:choruspass@localhost:5432/chorus"

# Email (Gmail example)
SMTP_HOST="smtp.gmail.com"
SMTP_PORT="587"
SMTP_USER="your-email@gmail.com"
SMTP_PASS="your-app-password"

# Notifications
NOTIFICATION_FROM_EMAIL="noreply@chorus.services"
NOTIFICATION_TO_EMAIL="anthony.lewis.rawlins@gmail.com"

# API Security
LEAD_API_KEY="your-secure-api-key-here"

3. Install Dependencies

npm install

4. Test the System

# Start development server
npm run dev

# Run tests (in separate terminal)
node test-lead-capture.js

Integration with Existing Components

Homepage Integration

The lead capture system is integrated with CTA buttons throughout the homepage:

// In HomePage component
const { isModalOpen, currentConfig, openLeadModal, closeLeadModal, handleLeadSuccess } = useLeadCapture();

// CTA buttons trigger modal
<Button onClick={() => openLeadModal('schedule_strategic_demo')}>
  Schedule Strategic Demo
</Button>

// Modal renders conditionally
{currentConfig && (
  <LeadCaptureModal
    open={isModalOpen}
    config={currentConfig}
    onClose={closeLeadModal}
    onSuccess={handleLeadSuccess}
  />
)}

Hero Section Integration

Enhanced hero section now includes lead capture functionality:

// Hero CTA buttons
<PrimaryButton onClick={() => openLeadModal('schedule_strategic_demo')}>
  Schedule Strategic Demo
</PrimaryButton>

<SecondaryButton onClick={() => openLeadModal('technical_deep_dive')}>
  Technical Deep Dive
</SecondaryButton>

Form Configurations by Lead Source

Lead Source	Phone	Address	Company	Custom Message	Purpose
Schedule Strategic Demo	✅	❌	✅	✅	Sales qualified leads
Technical Deep Dive	❌	❌	✅	✅	Technical evaluation
ROI Calculator	❌	❌	✅	❌	Business case development
Compliance Brief	✅	❌	✅	✅	Compliance/legal inquiries
Case Studies	❌	❌	✅	❌	Content download
Contact Form	✅	❌	✅	✅	General inquiries
Newsletter	❌	❌	❌	❌	Marketing list building

Security Measures

Rate Limiting

• IP-based: 5 requests per hour per IP
• Email-based: 3 requests per day per email
• Automatic blocking: Temporary blocks for exceeded limits

Input Validation

• Client-side: Real-time validation with user feedback
• Server-side: Comprehensive Zod schema validation
• Sanitization: HTML entity encoding and SQL injection prevention

GDPR Compliance

• Consent Management: Required GDPR consent checkbox
• Audit Trail: Complete consent history tracking
• Data Retention: Automatic 7-year retention scheduling
• Right to be Forgotten: Built-in data deletion framework

Phone Number Validation

// International phone validation
const phoneValidation = validatePhoneNumber(phone, countryCode);
if (!phoneValidation.isValid) {
  return error('Invalid phone number format');
}
const formattedPhone = phoneValidation.formatted; // E.164 format

Monitoring & Analytics

Built-in Analytics

• Lead source tracking
• Conversion rate monitoring
• Geographic distribution
• Time-based analysis

Integration Ready

• Google Analytics events
• Facebook Pixel conversion tracking
• Custom analytics platforms

Example Analytics Events

// Successful lead capture
gtag('event', 'lead_capture_success', {
  event_category: 'conversion',
  event_label: 'schedule_strategic_demo',
  value: 1
});

// Modal interactions
gtag('event', 'lead_modal_open', {
  event_category: 'engagement', 
  event_label: leadSource
});

Deployment Considerations

Production Checklist

• Database schema deployed
• Environment variables configured
• SMTP credentials tested
• API key generated and secured
• Rate limiting configured for production load
• SSL certificate configured
• GDPR privacy policy updated
• Email notification templates customized
• Analytics tracking verified

Performance Optimization

• Connection pooling for database
• Caching for dropdown data (countries, industries)
• Async email sending
• Rate limiter memory optimization

Maintenance Tasks

• Regular database cleanup for expired data
• Consent audit log monitoring
• Rate limit monitoring and adjustment
• Email delivery monitoring

Troubleshooting

Common Issues

Database Connection

# Check database connectivity
psql $DATABASE_URL -c "SELECT 1;"

Email Delivery

# Test SMTP configuration
node -e "
const nodemailer = require('nodemailer');
const transport = nodemailer.createTransport({
  host: process.env.SMTP_HOST,
  port: process.env.SMTP_PORT,
  auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS }
});
transport.verify().then(console.log).catch(console.error);
"

Rate Limiting Issues

• Check Redis/memory store connection
• Verify rate limit configuration
• Monitor rate limit logs

Error Codes

• 400: Validation error (check request format)
• 409: Duplicate email (email already exists)
• 429: Rate limit exceeded (wait before retry)
• 500: Server error (check logs)

Future Enhancements

Planned Features

• Multi-language form support
• Advanced bot detection (reCAPTCHA integration)
• CRM integration (HubSpot, Salesforce)
• Advanced analytics dashboard
• A/B testing for form configurations
• Custom field configuration
• Lead scoring algorithm
• Automated follow-up sequences

Integration Opportunities

• Marketing automation platforms
• Customer support systems
• Business intelligence tools
• Advanced consent management platforms

---

Support

For technical support or questions about the lead capture system:

• Email: anthony.lewis.rawlins@gmail.com
• Privacy inquiries: privacy@chorus.services

Compliance Notes

This system is designed to comply with:

• GDPR (General Data Protection Regulation)
• CCPA (California Consumer Privacy Act)
• CAN-SPAM Act (Email marketing compliance)
• Standard business practices for data retention and security

Regular compliance audits and updates are recommended as regulations evolve.