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
```sql
-- 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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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

```typescript
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

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

### 2. Environment Variables

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

```bash
# 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

```bash
npm install
```

### 4. Test the System

```bash
# 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:

```tsx
// 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:

```tsx
// 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
```typescript
// 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
```javascript
// 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**
```bash
# Check database connectivity
psql $DATABASE_URL -c "SELECT 1;"
```

**Email Delivery**
```bash
# 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](mailto:anthony.lewis.rawlins@gmail.com)
- Privacy inquiries: [privacy@chorus.services](mailto: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.