growth-quiz-engine

Configurable quiz funnel engine with conditional branching, multi-axis scoring, personalized results, and email capture. Built for conversion.

React 19 + TypeScript · Conditional Branching · 40%+ Lead Conversion · PDF Reports

---

Features

• Configurable Questions — Define questions, options, and flow via config files
• Conditional Branching — Show/skip questions based on previous answers
• Multi-Axis Scoring — 4-axis assessment engine (Phase, Severity, Impact, Readiness)
• 5 Result Personas — Personalized results mapped to severity brackets
• Personalized Email Reports — HTML email with results, modules, and next steps
• Email / Lead Capture — Gated results with consent-aware lead collection
• Mobile-First Design — Touch-optimized, 48px targets, iOS zoom prevention
• GA4 + Meta Pixel Ready — Pre-built event tracking for full funnel analytics
• A/B Testing — Built-in variant support via URL parameter (?variant=b)
• Exit Intent Modal — Re-engagement for desktop users about to leave
• Framer Motion Animations — Smooth page transitions and micro-interactions

Architecture

flowchart LR
    A[Landing Page] --> B[Q1: Multi-Select]
    B --> C[Q2: Severity Slider]
    C --> D{2+ selected?}
    D -->|Yes| E[Q3: Severity 2]
    D -->|No| F[Interstitial 1]
    E --> F
    F --> G[Q5-Q7b: Profile]
    G --> H[Interstitial 2]
    H --> I[Q8-Q9: Goals]
    I --> J[Email Gate]
    J --> K[Loading Screen]
    K --> L[Result Page]
    L --> M[Thank You + CTA]

    subgraph Scoring Engine
        S1[Phase Score] --> SR[Result Router]
        S2[Severity Score] --> SR
        S3[Impact Index] --> SR
        S4[Readiness Score] --> SR
        SR --> P[Persona Match]
    end

    J -.->|Webhook + Email| N[CRM / Resend API]

Loading

Quick Start

# Clone the repository
git clone https://github.com/your-username/growth-quiz-engine.git
cd growth-quiz-engine

# Install dependencies
npm install

# Start development server
npm run dev

Open http://localhost:5173 to see the quiz.

Project Structure

growth-quiz-engine/
├── src/
│   ├── lib/                    # Business logic & configuration
│   │   ├── constants.ts        # Brand config, quiz timing, A/B titles
│   │   ├── questions.ts        # Question definitions (9 questions)
│   │   ├── scoring.ts          # Multi-axis scoring engine
│   │   ├── results.ts          # Result type configs (5 personas)
│   │   ├── analytics.ts        # GA4 + Meta Pixel event tracking
│   │   └── webhook.ts          # CRM webhook + email API
│   ├── types/                  # TypeScript type definitions
│   ├── context/                # React Context (quiz state management)
│   ├── pages/                  # Screen components (18 screens)
│   │   ├── hero/               # Landing page sections
│   │   ├── Q1Concerns.tsx      # Multi-select concerns
│   │   ├── Q2Severity1.tsx     # Severity slider + frequency
│   │   ├── ResultScreen.tsx    # Personalized result page
│   │   └── ...
│   ├── components/
│   │   ├── ui/                 # shadcn/ui components
│   │   ├── quiz/               # Quiz-specific components
│   │   └── layout/             # Layout components
│   ├── hooks/                  # Custom React hooks
│   └── router/                 # Screen routing logic
├── api/
│   └── send-email.ts           # Vercel serverless email function
├── config/                     # Example configuration files
│   ├── questions.json          # Question definitions
│   ├── scoring.json            # Scoring rules
│   └── personas.json           # Result type configurations
├── docs/
│   └── customization.md        # Detailed customization guide
├── public/                     # Static assets
└── package.json

Customization

Questions

Edit src/lib/questions.ts to modify questions, options, and flow:

export const QUESTIONS: QuestionConfig[] = [
  {
    id: 'primaryConcerns',
    screenId: 'q1-concerns',
    question: 'Which areas affect you the most?',
    type: 'multi',
    options: [
      { id: 'energy-fatigue', label: 'Energy & Fatigue', icon: 'Zap', emoji: '⚡' },
      // ... add your own options
    ],
  },
  // ... add more questions
]

Scoring

Edit src/lib/scoring.ts to modify the 4-axis scoring engine:

• Phase Score (0-10) — Based on age + lifecycle phase
• Severity Score (0-44) — Weighted concern severity with frequency multipliers
• Impact Index — Raw average of severity sliders (low/medium/high)
• Readiness Score (0-14) — Assessment status + action readiness + current approach

Result Personas

Edit src/lib/results.ts to customize the 5 result types:

export const RESULT_TYPES: Record<ResultType, ResultTypeConfig> = {
  'mild-concerns': {
    headline: 'Mild Concerns Detected',
    subtitle: 'Your body is sending early signals...',
    actionModules: [
      { moduleRange: 'Module 1-3', title: 'Foundations', ... },
    ],
  },
  // ...
}

Branding

Edit src/lib/constants.ts to change brand name, colors, and links:

export const BRAND = {
  name: 'YourBrand',
  company: 'Your Company',
  tagline: 'Your tagline here.',
  // ...
}

Colors are configured in tailwind.config.js and src/index.css.

See docs/customization.md for the full customization guide.

Deployment

Vercel (Recommended)

1. Push to GitHub
2. Import in Vercel
3. Set environment variables:
   • RESEND_API_KEY — For email sending (resend.com)
   • VITE_WEBHOOK_URL — (Optional) CRM webhook endpoint

Any Static Host

npm run build
# Deploy the `dist/` folder to any static host

Note: The email API (/api/send-email) requires a serverless runtime (Vercel, Netlify Functions, etc.)

Environment Variables

Variable	Required	Description
RESEND_API_KEY	For emails	Resend API key for sending result emails
VITE_WEBHOOK_URL	Optional	CRM webhook endpoint for lead data

Copy .env.example to .env and fill in your values.

Tech Stack

Technology	Purpose
React 19	UI framework
TypeScript 5.9	Type safety
Vite 7	Build tool
Tailwind CSS 3.4	Styling
Framer Motion 12	Animations
Radix UI	Accessible primitives
Resend	Email delivery
Zod 4	Schema validation
Vercel	Hosting + serverless

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT — Dominik Tsatskin