Premium System Documentation

Technical guide for Snuggli's monetization infrastructure

⚠️ Individual subscriptions are disabled

As of the current release, Snuggli does not sell individual user subscriptions. Every signed-in user has full access to every feature. All consumer-facing upgrade prompts, paywalls, trial banners, and grace-period banners have been disabled (rendered as no-op components). The Stripe-backed monetization layer below is retained only for institutional billing (Snuggli Campus / partner plans) — institutions pay for cohort-wide access, individuals never pay personally.

System Overview

Snuggli operates on a single monetization pillar with all core wellness features free for every user:

  • Free for individuals — every feature (Araba, journal, mood, audio, goals, community) is included at no cost. No individual subscriptions are sold.
  • Snuggli for Institutions — schools, universities, NGOs, and employers pay for cohort access, wellbeing dashboards (15+ user minimum, aggregate only), custom branded resources, and reporting.

Feature Flag System

Premium features are controlled via feature flags. Use the usePremium() hook:

import { usePremium, PREMIUM_FLAGS } from '@/components/premium/PremiumProvider';

function MyComponent() {
  const { hasFeature, isPremium, isSponsored } = usePremium();
  
  // Check specific feature
  if (hasFeature(PREMIUM_FLAGS.INSIGHTS_PLUS)) {
    // Show premium insights
  }
  
  // Check any premium status
  if (isPremium) {
    // User has plus or sponsored access
  }
}

Available Flags

INSIGHTS_PLUSAUDIO_LIBRARYPREMIUM_THEMESPREMIUM_PROGRAMSPREMIUM_TEMPLATESJOURNAL_SEARCHJOURNAL_PINNINGEXPORT_PDFADVANCED_CORRELATIONSINSTITUTION_DASHBOARD

Gating Premium Content

Use the PremiumGate component to wrap premium-only content:

import PremiumGate, { PremiumBadge, PremiumNudge } from '@/components/premium/PremiumGate';

// Wrap content that requires premium
<PremiumGate 
  feature={PREMIUM_FLAGS.INSIGHTS_PLUS}
  upgradeMessage="Unlock deep mood insights"
>
  <InsightsChart />
</PremiumGate>

// Show premium badge
<h3>Advanced Analytics <PremiumBadge /></h3>

// Show upgrade nudge inline
<PremiumNudge 
  feature={PREMIUM_FLAGS.AUDIO_LIBRARY}
  message="Unlock guided meditations"
/>

Data Models

Subscription Entity

{
  tier: "free" | "plus" | "sponsored",
  status: "active" | "cancelled" | "expired" | "trial",
  billing_cycle: "monthly" | "annual",
  renewal_date: datetime,
  institution_id: string (if sponsored),
  premium_flags: string[],
  stripe_subscription_id: string
}

Institution Entity

{
  name: string,
  type: "university" | "high_school" | "ngo" | "church" | ...,
  join_code: string,
  seats_licensed: number,
  seats_used: number,
  plan: "basic" | "plus" | "impact",
  custom_resources: [{title, url, phone, description}],
  aggregate_dashboard_enabled: boolean,
  minimum_cohort_size: number (default: 15)
}

Adding Guided Programs

Programs are stored in the GuidedProgram entity. Create via admin or API:

await base44.entities.GuidedProgram.create({
  title: "7-Day Gratitude Journey",
  description: "Transform your perspective...",
  duration_days: 7,
  category: "gratitude",
  difficulty: "beginner",
  is_premium: true,
  icon_emoji: "🙏",
  color: "#FF9D03",
  days: [
    {
      day_number: 1,
      title: "Finding Gratitude",
      journal_prompt: "List 3 things you're grateful for...",
      practice_description: "5-minute gratitude meditation",
      practice_type: "meditation",
      practice_duration_minutes: 5,
      educational_content: "Why gratitude matters...",
      araba_check_in: true
    },
    // ... more days
  ],
  completion_points: 100
});

Onboarding New Institutions

  1. 1. Create Institution record

    Set name, type, contact info, plan, and seat count

  2. 2. Generate join code

    Unique code like "SNUG-ABC123" for users to join

  3. 3. Configure custom resources (optional)

    Add on-campus counseling, chaplains, hotlines

  4. 4. Set branding (optional)

    Logo, color, welcome message

  5. 5. Enable dashboard (for Plus/Impact plans)

    Set aggregate_dashboard_enabled: true

  6. 6. Add coordinators

    Create InstitutionMember records with role: "coordinator"

Privacy & Safety Rules

Minimum Cohort Size

Institution dashboards require 15+ users before showing any aggregate data

No Individual Data

Institution coordinators NEVER see individual user entries or mood logs

Core Features Stay Free

Basic mood tracking, journaling, and Araba chat must never be paywalled

Not Clinical

All premium features include disclaimers that they're for reflection only, not diagnosis

Ethical Upsell Guidelines

DO:

  • Show value-based messages: "Want deeper insights?"
  • Celebrate user achievements before suggesting upgrade
  • Be clear about what's free vs premium
  • Show prices clearly

DON'T:

  • Use fear-based copy ("You'll lose your progress...")
  • Block access to safety features
  • Show aggressive pop-ups
  • Use countdown timers or fake urgency

Billing Integration (Stripe)

Payment processing uses Stripe. Key webhook events to handle:

// Webhook events to handle:
- checkout.session.completed → Create/activate subscription
- invoice.paid → Renew subscription
- invoice.payment_failed → Set status to 'grace_period'
- customer.subscription.deleted → Set status to 'cancelled'

// Subscription tiers map to Stripe products:
- Snuggli Plus Monthly: price_xxx
- Snuggli Plus Annual: price_yyy

// Grace period: 7 days after failed payment
// After grace period: downgrade to free (don't delete data)

Future Premium Features (Planned)

Mentor View

Let users share subset of insights with trusted adult (opt-in only)

Curriculum Hooks

Integration with youth program curricula

White Label

Fully branded version for enterprise partners

API Access

For institutions with custom integrations