SAM AI Funnels Module - Complete Architecture Plan

Created: 2025-12-31
Author: CTO Architect Agent
Status: APPROVED FOR IMPLEMENTATION
Module: sam_ai_funnels

EXECUTIVE SUMMARY

This document defines the complete architecture for a new "FUNNELS" tab in Odoo 18's website builder, fully integrated with SAM AI for automated funnel creation and copywriting.

What We're Building:
- New FUNNELS tab in website builder sidebar (alongside BLOCKS, CUSTOMIZE, THEME)
- 46 drag-and-drop snippet templates for sales funnels
- 6 complete funnel templates (multi-page sequences)
- Native CRM and mailing list integration
- SAM AI integration for funnel building and copy generation

Why:
- Eliminate need for external funnel tools (ClickFunnels, Leadpages)
- Native Odoo integration (CRM, mailing, payments)
- SAM AI can build funnels conversationally
- Single platform for entire business

MODULE IDENTITY

Module Name: SAM AI Funnels
Technical Name: sam_ai_funnels
Location: D:\SAMAI-18-SaaS\ai_sam\sam_ai_funnels\
Version: 18.0.1.0.0
Dependencies: website, crm, mass_mailing, ai_brain, ai_sam

DATA MODELS

Model 1: funnel.definition

Master record for a complete funnel (multi-page sequence).

class FunnelDefinition(models.Model):
    _name = 'funnel.definition'
    _description = 'Sales Funnel Definition'
    _inherit = ['mail.thread', 'mail.activity.mixin']

    # Core Identity
    name = fields.Char('Funnel Name', required=True)
    description = fields.Text('Description')
    funnel_type = fields.Selection([
        ('opt_in', 'Simple Opt-in'),
        ('lead_magnet', 'Lead Magnet'),
        ('quiz', 'Quiz Funnel'),
        ('eoi', 'Expression of Interest'),
        ('product_launch', 'Product Launch'),
        ('webinar', 'Webinar'),
        ('custom', 'Custom'),
    ], default='custom')

    # Pages (One2many)
    page_ids = fields.One2many('funnel.page', 'funnel_id', string='Funnel Pages')
    page_count = fields.Integer(compute='_compute_page_count')

    # Template Source
    template_id = fields.Many2one('funnel.template', string='Based on Template')

    # CRM Integration
    crm_team_id = fields.Many2one('crm.team', string='Sales Team')
    default_tag_ids = fields.Many2many('crm.tag', string='Lead Tags')

    # Mailing Integration
    mailing_list_id = fields.Many2one('mailing.list', string='Mailing List')

    # Analytics
    total_views = fields.Integer(compute='_compute_analytics')
    total_conversions = fields.Integer(compute='_compute_analytics')
    conversion_rate = fields.Float(compute='_compute_analytics')

    # State
    state = fields.Selection([
        ('draft', 'Draft'),
        ('active', 'Active'),
        ('paused', 'Paused'),
        ('archived', 'Archived'),
    ], default='draft')

    # SAM AI Integration
    canvas_id = fields.Many2one('canvas', string='Workflow Canvas')
    ai_generated_copy = fields.Boolean('Copy Generated by SAM')

Model 2: funnel.page

Individual page within a funnel.

class FunnelPage(models.Model):
    _name = 'funnel.page'
    _description = 'Funnel Page'
    _order = 'sequence, id'

    # Core Identity
    name = fields.Char('Page Name', required=True)
    funnel_id = fields.Many2one('funnel.definition', required=True, ondelete='cascade')
    sequence = fields.Integer('Sequence', default=10)

    # Page Type
    page_type = fields.Selection([
        ('squeeze', 'Squeeze Page'),
        ('lead_magnet', 'Lead Magnet Page'),
        ('sales', 'Sales Page'),
        ('order', 'Order/Checkout'),
        ('upsell', 'Upsell Page'),
        ('thank_you', 'Thank You Page'),
        ('quiz_intro', 'Quiz Introduction'),
        ('quiz_questions', 'Quiz Questions'),
        ('quiz_gate', 'Quiz Email Gate'),
        ('quiz_results', 'Quiz Results'),
        ('webinar_registration', 'Webinar Registration'),
        ('webinar_confirmation', 'Webinar Confirmation'),
        ('webinar_replay', 'Webinar Replay'),
        ('custom', 'Custom Page'),
    ])

    # Website Integration
    website_page_id = fields.Many2one('website.page', string='Website Page')
    page_url = fields.Char('URL Slug')
    full_url = fields.Char(compute='_compute_full_url')

    # Snippet Configuration (JSON)
    snippet_config = fields.Text('Snippet Configuration', default='[]')

    # Redirect After Action
    next_page_id = fields.Many2one('funnel.page', string='Next Page')
    redirect_url = fields.Char('External Redirect URL')

    # Analytics
    view_count = fields.Integer('Views')
    unique_visitors = fields.Integer('Unique Visitors')
    form_submissions = fields.Integer('Form Submissions')
    conversion_rate = fields.Float(compute='_compute_conversion_rate')

Model 3: funnel.template

Reusable funnel blueprints.

class FunnelTemplate(models.Model):
    _name = 'funnel.template'
    _description = 'Funnel Template'

    name = fields.Char('Template Name', required=True)
    description = fields.Text('Description')
    funnel_type = fields.Selection([...])  # Same as funnel.definition

    # Template Structure (JSON)
    template_structure = fields.Text('Template Structure')

    # Preview
    thumbnail = fields.Binary('Thumbnail')
    preview_url = fields.Char('Preview URL')

    # Usage Stats
    usage_count = fields.Integer('Times Used')

    # Visibility
    visibility = fields.Selection([
        ('private', 'Private'),
        ('company', 'Company'),
        ('public', 'Public'),
    ], default='company')

Model 4: funnel.snippet

Registry of available funnel snippets.

class FunnelSnippet(models.Model):
    _name = 'funnel.snippet'
    _description = 'Funnel Snippet Definition'

    name = fields.Char('Snippet Name', required=True)
    technical_name = fields.Char('Technical Name', required=True)

    category = fields.Selection([
        ('hero', 'Hero Sections'),
        ('problem_story', 'Problem & Story'),
        ('solution_benefits', 'Solution & Benefits'),
        ('social_proof', 'Social Proof'),
        ('offers_pricing', 'Offers & Pricing'),
        ('cta_forms', 'CTAs & Forms'),
        ('quiz', 'Quiz Elements'),
        ('urgency_trust', 'Urgency & Trust'),
        ('utility', 'Utility'),
    ])

    # XML Template Reference
    template_xml_id = fields.Char('XML Template ID')

    # Field Schema (JSON)
    field_schema = fields.Text('Field Schema')

    # Preview
    thumbnail = fields.Binary('Thumbnail')

    # SAM AI Knowledge
    copywriting_hints = fields.Text('Copywriting Hints for SAM')

Model 5: funnel.conversion

Track every conversion event.

class FunnelConversion(models.Model):
    _name = 'funnel.conversion'
    _description = 'Funnel Conversion Event'

    # Context
    funnel_id = fields.Many2one('funnel.definition', required=True)
    page_id = fields.Many2one('funnel.page', required=True)

    # Visitor
    visitor_id = fields.Char('Visitor ID')
    partner_id = fields.Many2one('res.partner', string='Contact')

    # Event
    event_type = fields.Selection([
        ('page_view', 'Page View'),
        ('form_submit', 'Form Submission'),
        ('cta_click', 'CTA Click'),
        ('quiz_start', 'Quiz Started'),
        ('quiz_complete', 'Quiz Completed'),
        ('purchase', 'Purchase'),
    ])

    # Metadata
    timestamp = fields.Datetime(default=fields.Datetime.now)
    session_data = fields.Text('Session Data')
    utm_source = fields.Char('UTM Source')
    utm_medium = fields.Char('UTM Medium')
    utm_campaign = fields.Char('UTM Campaign')

    # CRM Link
    lead_id = fields.Many2one('crm.lead', string='Created Lead')

FILE STRUCTURE

sam_ai_funnels/
├── __manifest__.py
├── __init__.py
├── models/
│   ├── __init__.py
│   ├── funnel_definition.py
│   ├── funnel_page.py
│   ├── funnel_template.py
│   ├── funnel_snippet.py
│   └── funnel_conversion.py
├── controllers/
│   ├── __init__.py
│   ├── funnel_controller.py
│   └── funnel_form_controller.py
├── views/
│   ├── funnel_definition_views.xml
│   ├── funnel_page_views.xml
│   ├── funnel_template_views.xml
│   ├── funnel_menus.xml
│   └── snippets/
│       ├── options.xml
│       ├── s_hero_minimal.xml
│       ├── s_hero_full.xml
│       └── ... (all 46 snippets)
├── data/
│   ├── funnel_templates.xml
│   ├── funnel_snippets.xml
│   └── ir_asset.xml
├── static/
│   └── src/
│       ├── snippets/
│       │   ├── s_hero_minimal/
│       │   │   ├── 000.js
│       │   │   └── 000.scss
│       │   └── ... (all snippets)
│       ├── js/
│       │   ├── funnel_snippet_options.js
│       │   └── funnel_analytics.js
│       ├── css/
│       │   └── funnel_snippets.scss
│       └── img/
│           └── thumbnails/
└── security/
    └── ir.model.access.csv

SNIPPET CATEGORIES (46 Total)

Category	Count	Snippets
Complete Funnels	6	opt_in, lead_magnet, quiz, eoi, product_launch, webinar
Hero Sections	3	hero_minimal, hero_full, hero_video
Problem & Story	3	problem_agitation, story_bridge, before_after
Solution & Benefits	4	solution_reveal, benefits_stack, features_grid, how_it_works
Social Proof	6	testimonial_single, testimonial_grid, testimonial_video, trust_badges, case_study_preview, stats_bar
Offers & Pricing	5	offer_breakdown, bonus_stack, price_reveal, pricing_table, guarantee
CTAs & Forms	5	opt_in_form, cta_inline, cta_button_block, final_cta, ps_section
Quiz Elements	5	quiz_intro, quiz_question, quiz_progress, quiz_gate, quiz_results
Urgency & Trust	4	countdown_timer, urgency_bar, objection_handler, risk_reversal
Utility	5	divider_styled, spacer, video_embed, image_text_split, bullet_list

IMPLEMENTATION PHASES

Phase 1: Foundation

Module skeleton + manifest
5 core models
Basic views and menus
Security rules

Phase 2: Core Snippets (15)

FUNNELS tab in website builder
15 MVP snippets
Customize panel options
Thumbnails

Phase 3: Form Integration

Form submission controller
CRM lead creation
Mailing list subscription
UTM capture
Conversion tracking

Phase 4: Complete Funnels

6 funnel templates
Multi-page generation
Page linking
Analytics dashboard

Phase 5: Remaining Snippets (31)

Complete all 46 snippets
Full snippet library

Phase 6: SAM AI Integration

Create funnel from chat API
Copywriting knowledge base
Intent detection
Copy generation

Phase 7: Quiz Logic

Quiz state management
Branching logic
Score calculation
Results personalization

SAM AI INTEGRATION

API Endpoint

@http.route('/sam_ai_funnels/create_from_chat', type='json', auth='user')
def create_funnel_from_chat(self, funnel_spec):
    """
    SAM calls this to create a funnel programmatically.

    Args:
        funnel_spec: {
            'name': 'Q1 Webinar Funnel',
            'funnel_type': 'webinar',
            'crm_team_id': 2,
            'pages': [
                {
                    'name': 'Registration',
                    'page_type': 'webinar_registration',
                    'snippets': [
                        {'type': 'hero_full', 'config': {...}},
                        {'type': 'opt_in_form', 'config': {...}}
                    ]
                }
            ]
        }
    """

Copywriting Knowledge

SAM will have knowledge of:
- Headline formulas per snippet type
- PAS framework for problem sections
- Benefit transformation techniques
- CTA copy best practices
- Quiz result personalization

SUCCESS CRITERIA

The module is complete when:
- [ ] FUNNELS tab appears in website builder
- [ ] All 46 snippets are draggable
- [ ] All snippets have customization options
- [ ] Forms integrate with CRM and mailing
- [ ] 6 complete funnels create multi-page sequences
- [ ] SAM can build funnels from chat
- [ ] SAM can generate copy for each snippet
- [ ] Quiz logic works with branching
- [ ] All snippets are mobile responsive

FUNNELS-TAB-REQUIREMENTS.md - Original requirements
Current State - SAM AI ecosystem overview

END OF ARCHITECTURE PLAN