🎯 Funnels Module

📖 Overview

The Funnels module powers DashClicks' landing page funnel builder, enabling agencies to create multi-step marketing funnels with custom domains, conversion tracking, A/B testing, and detailed analytics. Funnels are used for lead generation campaigns, sales pages, opt-in forms, and customer onboarding flows.

File Path: internal/api/v1/funnels/

Key Capabilities

• Multi-Step Funnels: Create sequential page flows (landing → opt-in → thank you)
• Custom Domains: Map funnels to custom/white-label domains
• Block Builder: Drag-and-drop content blocks for page construction
• Templates: Pre-built funnel templates for quick setup
• Analytics: Track views, conversions, bounce rates, and revenue
• A/B Testing: Split traffic between funnel variants
• Tag Management: Organize funnels with custom tags
• Sales Tracking: Link funnels to CRM deals and revenue

🗄️ Collections Used

funnels

• Model: shared/models/funnel.js
• Purpose: Funnel configuration and metadata
• Key Fields:
  • account_id (ObjectId) - Owner account
  • name (String) - Funnel title
  • slug (String) - URL-safe identifier
  • domain_id (ObjectId) - Custom domain reference
  • steps (Array) - Ordered funnel steps
  • template_id (ObjectId) - Source template
  • status ('draft' | 'published' | 'archived')
  • analytics (Object) - Aggregated stats

funnel.blocks

• Purpose: Page content blocks (text, images, forms, buttons)
• Key Fields:
  • step_id (ObjectId) - Parent funnel step
  • type (String) - Block type enum
  • content (Object) - Block configuration
  • order (Number) - Display order

funnel.domains

• Purpose: Custom domain mappings
• Key Fields:
  • domain (String) - Domain name
  • account_id (ObjectId) - Owner
  • verified (Boolean) - DNS verification status
  • ssl_enabled (Boolean) - HTTPS status

funnel.analytics

• Purpose: Visit and conversion event storage
• Key Fields:
  • funnel_id (ObjectId)
  • step_id (ObjectId)
  • event_type ('view' | 'conversion' | 'exit')
  • visitor_id (String) - Anonymous tracking ID
  • timestamp (Date)
  • metadata (Object) - UTM params, referrer, etc.

funnel.templates

• Purpose: Pre-built funnel templates
• Key Fields:
  • name (String)
  • category (String)
  • thumbnail (String)
  • is_global (Boolean) - Available to all accounts

funnel.tags

• Purpose: Funnel categorization tags
• Key Fields:
  • account_id (ObjectId)
  • name (String)
  • color (String)

🏗️ Architecture

funnels/
├── services/
│   ├── funnels.service.js          # Funnel CRUD
│   ├── block.service.js            # Block management
│   ├── domains.service.js          # Domain config
│   ├── analytics.service.js        # Analytics queries
│   ├── sale.service.js             # Revenue tracking
│   ├── tags.service.js             # Tag management
│   ├── global.funnel.templates.service.js  # Templates
│   └── step.redirect.service.js    # Step redirects
├── controllers/       # Express handlers
├── routes/           # API endpoints
├── validations/      # Joi schemas
└── utils/            # Helpers

🔄 Data Flow

Funnel Creation Flow

flowchart TD
    A[User Creates Funnel] --> B{From Template?}
    B -->|Yes| C[Clone Template Steps/Blocks]
    B -->|No| D[Create Empty Funnel]

    C --> E[Generate Unique Slug]
    D --> E

    E --> F{Custom Domain?}
    F -->|Yes| G[Verify Domain DNS]
    F -->|No| H[Use Platform Domain]

    G --> I[Assign Domain to Funnel]
    H --> I

    I --> J[Set Status: Draft]
    J --> K[Return Funnel ID]

Visitor Tracking Flow

sequenceDiagram
    participant Visitor
    participant Funnel
    participant Analytics
    participant DB

    Visitor->>Funnel: Visit Step 1
    Funnel->>Analytics: Track 'view' event
    Analytics->>DB: Create analytics record

    Visitor->>Funnel: Submit form on Step 2
    Funnel->>Analytics: Track 'conversion' event
    Analytics->>DB: Create conversion record

    Visitor->>Funnel: Reach final step
    Funnel->>Analytics: Track 'completion' event
    Analytics->>DB: Update funnel completion count

🔧 Core Services

Funnels Service

Functions:

• createFunnel(accountId, data) - Create new funnel
• getFunnel(funnelId, accountId) - Retrieve funnel with steps/blocks
• updateFunnel(funnelId, updates) - Update funnel metadata
• deleteFunnel(funnelId) - Soft delete funnel
• publishFunnel(funnelId) - Change status to 'published'
• duplicateFunnel(funnelId) - Clone funnel with new slug

Analytics Service

Functions:

• getFunnelAnalytics(funnelId, dateRange) - Aggregated stats
• getStepAnalytics(stepId) - Per-step conversion rates
• getVisitorJourney(visitorId) - Individual visitor path
• calculateConversionRate(funnelId) - Overall funnel performance

Aggregation Example:

// Analytics aggregation pipeline
const stats = await FunnelAnalytics.aggregate([
  { $match: { funnel_id: funnelId, timestamp: { $gte: startDate } } },
  {
    $group: {
      _id: '$step_id',
      views: { $sum: { $cond: [{ $eq: ['$event_type', 'view'] }, 1, 0] } },
      conversions: { $sum: { $cond: [{ $eq: ['$event_type', 'conversion'] }, 1, 0] } },
    },
  },
  {
    $project: {
      step_id: '$_id',
      views: 1,
      conversions: 1,
      conversion_rate: {
        $cond: [{ $gt: ['$views', 0] }, { $divide: ['$conversions', '$views'] }, 0],
      },
    },
  },
]);

Domains Service

Functions:

• addDomain(accountId, domain) - Register custom domain
• verifyDomain(domainId) - Check DNS records
• enableSSL(domainId) - Request SSL certificate
• deleteDomain(domainId) - Remove domain mapping

Block Service

Functions:

• createBlock(stepId, blockData) - Add block to step
• updateBlock(blockId, content) - Update block configuration
• reorderBlocks(stepId, blockIds) - Change display order
• deleteBlock(blockId) - Remove block

Tags Service

Functions:

• createTag(accountId, name, color) - Create tag
• assignTag(funnelId, tagId) - Tag funnel
• removeTag(funnelId, tagId) - Untag funnel
• listTags(accountId) - Get all tags

🔀 Integration Points

• Custom Domains - DNS management and SSL provisioning
• CRM Deals - Link funnel conversions to sales pipeline
• Email Marketing - Trigger campaigns from funnel events
• Analytics Dashboard - Aggregate funnel performance metrics

📊 Analytics Metrics

Funnel-Level:

• Total Views
• Unique Visitors
• Overall Conversion Rate
• Revenue Generated
• Average Time to Convert

Step-Level:

• Step Views
• Exit Rate
• Drop-off Percentage
• Time on Step
• Next Step Conversion

Visitor-Level:

• Journey Path
• Source/UTM Parameters
• Device/Browser
• Geographic Location

⚠️ Important Notes

• 🔒 Slug Uniqueness: Funnel slugs must be unique per account
• 🌐 Domain Verification: Custom domains require DNS CNAME records
• 📊 Analytics Retention: Events stored for 24 months
• 🚀 Publishing: Only published funnels are publicly accessible
• 💾 Soft Deletes: Deleted funnels preserved for 30 days

---

📚 Controller Documentation

Comprehensive documentation for all Funnels controllers:

Core Controllers

• Funnels Controller (45KB) - Complete funnel CRUD, step management, component versioning, Cloudflare edge caching
• Analytics Controller (17KB) - Conversion tracking, metrics, UTM attribution, revenue analytics
• Sales Controller (12KB) - Payment transactions, Stripe/Square integration, sales reporting

Configuration Controllers

• Domains Controller (15KB) - Custom domain setup, SSL certificates, DNS configuration
• Global Templates Controller (17KB) - Template marketplace, categories, cloning system
• Blocks Controller (16KB) - Reusable UI components library, global and user blocks

Utility Controllers

• Tags Controller (11KB) - Funnel organization and categorization
• Step Redirect Controller (8KB) - URL redirect handling for funnel steps