a time-series or relational store. Use a feature flag service to control AI rollout.

Step 2: AI Decision Engine

Route requests through a model gateway that handles fallbacks, structured outputs, and cost tracking. Never expose raw LLM responses to production UI without validation.

Step 3: Dynamic Onboarding Flow

Generate personalized next steps, copy, and UI variants based on user segment and real-time behavior. Cache results where appropriate to control latency and cost.

Step 4: Feedback Loop & Experimentation

Log AI decisions, user responses, and conversion outcomes. Feed results back into the decision engine for continuous optimization.

TypeScript Implementation

// src/growth/ai-onboarding-engine.ts
import { generateObject } from 'ai';
import { openai } from '@ai-sdk/openai';
import { z } from 'zod';
import { createClient } from '@supabase/supabase-js';
import { track } from './analytics';

const supabase = createClient(process.env.SUPABASE_URL!, process.env.SUPABASE_SERVICE_KEY!);

const OnboardingStepSchema = z.object({
  step_id: z.string().uuid(),
  title: z.string().min(1).max(60),
  description: z.string().max(200),
  action_label: z.string().max(30),
  estimated_time_seconds: z.number().int().min(5).max(120),
  confidence_score: z.number().min(0).max(1),
});

type OnboardingStep = z.infer<typeof OnboardingStepSchema>;

interface UserContext {
  user_id: string;
  segment: 'free_trial' | 'enterprise_eval' | 'self_serve';
  completed_steps: string[];
  last_action: string;
  time_on_page_seconds: number;
}

export class AIOnboardingEngine {
  private model = openai('gpt-4o-mini');
  private fallbackModel = openai('gpt-3.5-turbo');

  async generateNextStep(context: UserContext): Promise<OnboardingStep> {
    const prompt = this.buildPrompt(context);
    
    try {
      const { object } = await generateObject({
        model: this.model,
        schema: OnboardingStepSchema,
        prompt,
        temperature: 0.3,
        maxTokens: 300,
      });

      await track('ai_onboarding_step_generated', {
        user_id: context.user_id,
        step_id: object.step_id,
        model: 'gpt-4o-mini',
        confidence: object.confidence_score,
      });

      return object;
    } catch (error) {
      // Fallback to cheaper model on rate limit or timeout
      const { object } = await generateObject({
        model: this.fallbackModel,
        schema: OnboardingStepSchema,
        prompt,
        temperature: 0.3,
        maxTokens: 300,
      });

      await track('ai_onboarding_step_fallback', {
        user_id: context.user_id,
        model: 'gpt-3.5-turbo',
      });

      return object;
    }
  }

  private buildPrompt(ctx: UserContext): string {
    return `
      You are a growth optimization engine for a SaaS product.
      Generate the next onboarding step for a user with this context:
      - Segment: ${ctx.segment}
      - Completed steps: ${ctx.completed_steps.join(', ') || 'none'}
      - Last action: ${ctx.last_action}
      - Time on page: ${ctx.time_on_page_seconds}s
      
      Rules:
      - Keep steps under 2 minutes to reduce drop-off
      - Prioritize actions that unlock core value
      - Output only valid JSON matching the schema
      - Confidence score reflects historical conversion probability for this segment
    `;
  }
}

Architecture Rationale

1. Structured Outputs: Zod schemas enforce contract stability. LLMs return predictable JSON that integrates cleanly with frontend state management and database constraints.
2. Fallback Routing: Primary model handles high-value segments; fallback triggers on rate limits, timeouts, or confidence thresholds. This prevents growth loops from breaking under load.
3. Cost Attribution: Every generation logs model, confidence, and segment. Engineering can calculate inference cost per activated user and optimize routing thresholds.
4. Event-Driven Feedback: track() pushes decisions to analytics and experiment services. The system becomes observable, enabling automated promotion of high-converting AI variants.
5. Caching Strategy: Cache generated steps per user segment and completed_step combination. Invalidate on product updates or conversion threshold shifts. Reduces latency by 60–80% and cuts inference spend.

Pitfall Guide

1. Treating LLMs as Deterministic APIs LLMs return probabilistic outputs. Without schema validation, confidence scoring, and fallback chains, UI states break and conversion tracking becomes unreliable. Always enforce structured outputs and define explicit error boundaries.

2. Ignoring Prompt and Model Versioning Prompt changes silently alter conversion patterns. Production systems require a prompt registry, version tagging, and automatic rollback when metrics drop below threshold. Treat prompts like infrastructure code, not marketing copy.

3. Over-Indexing on Vanity Metrics Measuring "AI interactions" or "tokens generated" doesn't correlate with growth. Track activation rate, time-to-value, drop-off points, and LTV:CAC. AI that increases engagement but doesn't move users toward core value destroys unit economics.

4. Skipping Rate Limiting and Circuit Breakers AI growth loops generate high-frequency requests during peak acquisition windows. Without circuit breakers, inference APIs throttle, latency spikes, and users abandon onboarding. Implement exponential backoff, request queuing, and graceful degradation to static fallbacks.

5. Neglecting Inference Cost Attribution Untracked AI spend silently erodes margins. Attribute costs per user segment, experiment variant, and conversion outcome. Route low-intent users to cheaper models or cached responses. Cap monthly inference budgets per growth cohort.

6. Feeding Low-Quality or Stale Data AI personalization degrades when user state, event timestamps, or segment tags are inconsistent. Implement data validation at ingestion, enforce idempotent event tracking, and run daily data health checks. Garbage in guarantees garbage out.

7. Lack of Observability for AI Decisions Without decision logging, you cannot diagnose conversion drops or optimize prompts. Log every AI generation with context, model version, confidence, and user outcome. Build dashboards that correlate AI decisions with activation funnels.

Best Practices from Production:

• Use feature flags to roll out AI variants incrementally by segment
• Implement confidence-based routing: high confidence → primary model, low confidence → fallback or static
• Cache aggressively but invalidate on product or pricing changes
• Run weekly prompt regression tests against historical conversion data
• Separate AI growth telemetry from product analytics to avoid metric contamination

Production Bundle

Action Checklist

• Define growth loop metrics: activation rate, time-to-value, drop-off points, LTV:CAC
• Implement structured output schemas with Zod or equivalent validation
• Deploy fallback routing with confidence thresholds and circuit breakers
• Build prompt registry with versioning, rollback, and automated regression tests
• Instrument inference cost attribution per user segment and experiment variant
• Create decision logging pipeline connecting AI outputs to conversion analytics
• Configure caching layer with segment-based invalidation rules
• Run weekly experiment reviews comparing AI variants against control groups

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Early-stage startup (<10k MAU)	AI-augmented with cached static fallbacks	Low traffic allows rapid iteration; caching controls spend	Low inference cost, high engineering velocity
Scaling SaaS (10k–100k MAU)	AI-first with segment routing & confidence thresholds	Volume requires cost control and fallback stability	Moderate cost, optimized by routing rules
Enterprise/Compliance	Deterministic AI with human-in-the-loop validation	Regulatory requirements demand auditability and control	Higher cost, reduced risk, slower iteration
Cost-constrained	Model distillation + aggressive caching + low-confidence routing	Maintains growth velocity while capping inference spend	Low cost, requires prompt optimization effort

Configuration Template

# .env.production
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_KEY=your-service-key
OPENAI_API_KEY=sk-...
AI_MODEL_PRIMARY=gpt-4o-mini
AI_MODEL_FALLBACK=gpt-3.5-turbo
AI_CONFIDENCE_THRESHOLD=0.75
AI_CACHE_TTL_SECONDS=300
AI_COST_CENT_SEGMENT=marketing_growth
FEATURE_FLAG_AI_ONBOARDING=enabled
ANALYTICS_ENDPOINT=https://your-analytics.collect/track

// src/growth/config.ts
export const AIConfig = {
  models: {
    primary: process.env.AI_MODEL_PRIMARY || 'gpt-4o-mini',
    fallback: process.env.AI_MODEL_FALLBACK || 'gpt-3.5-turbo',
  },
  thresholds: {
    confidence: parseFloat(process.env.AI_CONFIDENCE_THRESHOLD || '0.75'),
    maxTokens: 300,
    temperature: 0.3,
  },
  caching: {
    ttl: parseInt(process.env.AI_CACHE_TTL_SECONDS || '300', 10),
    segments: ['free_trial', 'enterprise_eval', 'self_serve'],
  },
  cost: {
    center: process.env.AI_COST_CENT_SEGMENT || 'marketing_growth',
    maxMonthlyBudget: 1500, // USD
  },
  featureFlags: {
    enabled: process.env.FEATURE_FLAG_AI_ONBOARDING === 'enabled',
  },
};

Quick Start Guide

1. Initialize the project: npm create vite@latest ai-growth-engine -- --template react-ts
2. Install dependencies: npm install ai @ai-sdk/openai zod @supabase/supabase-js
3. Copy configuration: Place .env.production and src/growth/config.ts in your project root and src directory
4. Deploy the engine: Import AIOnboardingEngine into your onboarding route, wire up event tracking, and enable the feature flag for 10% of traffic
5. Validate: Monitor confidence scores, fallback triggers, and activation rate deltas in your analytics dashboard. Promote to 50% traffic if conversion improves by ≥8% within 7 days