bakery-ia/docs/subscription-integration-guide.md

Subscription Tier Redesign - Integration Guide

Purpose: Step-by-step guide to integrate the new subscription components into your production application.

Prerequisites:

• All new components have been created
• Translation files have been updated
• Backend endpoints are ready for registration

---

🚀 Quick Start (15 minutes)

Step 1: Update Subscription Settings Page

File: frontend/src/pages/app/settings/subscription/SubscriptionPage.tsx

Add the new components to your existing subscription page:

import React, { useEffect, useState } from 'react';
import { useTranslation } from 'react-i18next';
import {
  SubscriptionPricingCards,
  UsageMetricCard,
  ROICalculator,
  PlanComparisonTable
} from '@/components/subscription';
import {
  trackSubscriptionPageViewed,
  trackUpgradeCTAClicked
} from '@/utils/subscriptionAnalytics';
import { useSubscription } from '@/hooks/useSubscription';
import { Package, Users, MapPin, TrendingUp, Database } from 'lucide-react';

export const SubscriptionPage: React.FC = () => {
  const { t } = useTranslation('subscription');
  const { subscription, usage, isLoading } = useSubscription();
  const [showComparison, setShowComparison] = useState(false);

  // Track page view
  useEffect(() => {
    if (subscription) {
      trackSubscriptionPageViewed(subscription.tier);
    }
  }, [subscription]);

  const handleUpgrade = (targetTier: string) => {
    trackUpgradeCTAClicked(
      subscription.tier,
      targetTier,
      'usage_metric_card'
    );
    // Navigate to upgrade flow
    window.location.href = `/app/settings/subscription/upgrade?plan=${targetTier}`;
  };

  if (isLoading) {
    return <div>Loading...</div>;
  }

  return (
    <div className="max-w-7xl mx-auto px-4 py-8 space-y-8">
      {/* Current Plan Overview */}
      <section>
        <h1 className="text-3xl font-bold mb-2">Subscription</h1>
        <p className="text-[var(--text-secondary)]">
          Manage your subscription and usage
        </p>
      </section>

      {/* Usage Metrics Grid */}
      <section>
        <h2 className="text-xl font-semibold mb-4">Usage & Limits</h2>
        <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">
          <UsageMetricCard
            metric="products"
            label={t('limits.products')}
            current={usage.products}
            limit={subscription.limits.products}
            trend={usage.productsTrend}
            predictedBreachDate={usage.productsPredictedBreach?.date}
            daysUntilBreach={usage.productsPredictedBreach?.days}
            currentTier={subscription.tier}
            upgradeTier="professional"
            upgradeLimit={500}
            onUpgrade={() => handleUpgrade('professional')}
            icon={<Package className="w-5 h-5" />}
          />

          <UsageMetricCard
            metric="users"
            label={t('limits.users')}
            current={usage.users}
            limit={subscription.limits.users}
            currentTier={subscription.tier}
            upgradeTier="professional"
            upgradeLimit={20}
            onUpgrade={() => handleUpgrade('professional')}
            icon={<Users className="w-5 h-5" />}
          />

          <UsageMetricCard
            metric="locations"
            label={t('limits.locations')}
            current={usage.locations}
            limit={subscription.limits.locations}
            currentTier={subscription.tier}
            upgradeTier="professional"
            upgradeLimit={3}
            onUpgrade={() => handleUpgrade('professional')}
            icon={<MapPin className="w-5 h-5" />}
          />

          <UsageMetricCard
            metric="training_jobs"
            label="Training Jobs"
            current={usage.trainingJobsToday}
            limit={subscription.limits.trainingJobsPerDay}
            unit="/day"
            currentTier={subscription.tier}
            upgradeTier="professional"
            upgradeLimit={5}
            onUpgrade={() => handleUpgrade('professional')}
            icon={<TrendingUp className="w-5 h-5" />}
          />

          <UsageMetricCard
            metric="forecasts"
            label="Forecasts"
            current={usage.forecastsToday}
            limit={subscription.limits.forecastsPerDay}
            unit="/day"
            currentTier={subscription.tier}
            upgradeTier="professional"
            upgradeLimit={100}
            onUpgrade={() => handleUpgrade('professional')}
            icon={<TrendingUp className="w-5 h-5" />}
          />

          <UsageMetricCard
            metric="storage"
            label="Storage"
            current={usage.storageUsedGB}
            limit={subscription.limits.storageGB}
            unit=" GB"
            currentTier={subscription.tier}
            upgradeTier="professional"
            upgradeLimit={10}
            onUpgrade={() => handleUpgrade('professional')}
            icon={<Database className="w-5 h-5" />}
          />
        </div>
      </section>

      {/* ROI Calculator (Starter tier only) */}
      {subscription.tier === 'starter' && (
        <section>
          <ROICalculator
            currentTier="starter"
            targetTier="professional"
            monthlyPrice={149}
            onUpgrade={() => handleUpgrade('professional')}
          />
        </section>
      )}

      {/* Plan Comparison Toggle */}
      <section>
        <button
          onClick={() => setShowComparison(!showComparison)}
          className="text-[var(--color-primary)] hover:underline font-medium"
        >
          {showComparison ? 'Hide' : 'Compare'} all plans
        </button>

        {showComparison && (
          <div className="mt-4">
            <PlanComparisonTable
              plans={subscription.availablePlans}
              currentTier={subscription.tier}
              onSelectPlan={(tier) => handleUpgrade(tier)}
            />
          </div>
        )}
      </section>

      {/* Current Plan Details */}
      <section>
        <h2 className="text-xl font-semibold mb-4">Current Plan</h2>
        {/* Your existing plan details component */}
      </section>
    </div>
  );
};

Step 2: Fetch Usage Forecast Data

Create/Update: frontend/src/hooks/useSubscription.ts

import { useQuery } from 'react-query';
import { subscriptionService } from '@/api/services/subscription';

interface UsageForecast {
  products: number;
  productsTrend: number[];
  productsPredictedBreach?: {
    date: string;
    days: number;
  };
  users: number;
  locations: number;
  trainingJobsToday: number;
  forecastsToday: number;
  storageUsedGB: number;
}

export const useSubscription = () => {
  const tenantId = getCurrentTenantId(); // Your auth logic

  // Fetch current subscription
  const { data: subscription, isLoading: isLoadingSubscription } = useQuery(
    ['subscription', tenantId],
    () => subscriptionService.getCurrentSubscription(tenantId)
  );

  // Fetch usage forecast
  const { data: forecast, isLoading: isLoadingForecast } = useQuery(
    ['usage-forecast', tenantId],
    () => subscriptionService.getUsageForecast(tenantId),
    {
      enabled: !!tenantId,
      refetchInterval: 5 * 60 * 1000, // Refresh every 5 minutes
    }
  );

  // Transform forecast data into usage object
  const usage: UsageForecast = forecast
    ? {
        products: forecast.metrics.find(m => m.metric === 'products')?.current || 0,
        productsTrend: forecast.metrics.find(m => m.metric === 'products')?.trend_data.map(d => d.value) || [],
        productsPredictedBreach: forecast.metrics.find(m => m.metric === 'products')?.days_until_breach
          ? {
              date: forecast.metrics.find(m => m.metric === 'products')!.predicted_breach_date!,
              days: forecast.metrics.find(m => m.metric === 'products')!.days_until_breach!,
            }
          : undefined,
        users: forecast.metrics.find(m => m.metric === 'users')?.current || 0,
        locations: forecast.metrics.find(m => m.metric === 'locations')?.current || 0,
        trainingJobsToday: forecast.metrics.find(m => m.metric === 'training_jobs')?.current || 0,
        forecastsToday: forecast.metrics.find(m => m.metric === 'forecasts')?.current || 0,
        storageUsedGB: forecast.metrics.find(m => m.metric === 'storage')?.current || 0,
      }
    : {} as UsageForecast;

  return {
    subscription,
    usage,
    isLoading: isLoadingSubscription || isLoadingForecast,
  };
};

Step 3: Add API Service Methods

Update: frontend/src/api/services/subscription.ts

export const subscriptionService = {
  // ... existing methods

  /**
   * Get usage forecast for all metrics
   */
  async getUsageForecast(tenantId: string) {
    const response = await apiClient.get(
      `/usage-forecast?tenant_id=${tenantId}`
    );
    return response.data;
  },

  /**
   * Track daily usage (called by cron jobs)
   */
  async trackDailyUsage(tenantId: string, metric: string, value: number) {
    const response = await apiClient.post('/usage-forecast/track-usage', {
      tenant_id: tenantId,
      metric,
      value,
    });
    return response.data;
  },
};

---

🔧 Backend Integration

Step 1: Register Usage Forecast Router

File: services/tenant/app/main.py

from fastapi import FastAPI
from app.api import subscription, plans, usage_forecast  # Add import

app = FastAPI()

# Register routers
app.include_router(subscription.router, prefix="/api/v1/subscription")
app.include_router(plans.router, prefix="/api/v1/plans")
app.include_router(usage_forecast.router, prefix="/api/v1")  # Add this line

Step 2: Set Up Daily Usage Tracking

Create: services/tenant/app/cron/track_daily_usage.py

"""
Daily Usage Tracking Cron Job

Run this script daily to snapshot current usage into Redis for trend analysis.
Schedule with cron: 0 0 * * * (daily at midnight)
"""

import asyncio
from datetime import datetime
from app.services.subscription_limit_service import SubscriptionLimitService
from app.api.usage_forecast import track_daily_usage
from app.core.database import get_all_active_tenants

async def track_all_tenants_usage():
    """Track usage for all active tenants"""
    tenants = await get_all_active_tenants()
    limit_service = SubscriptionLimitService()

    for tenant in tenants:
        try:
            # Get current usage
            usage = await limit_service.get_usage_summary(tenant.id)

            # Track each metric
            metrics_to_track = [
                ('products', usage['products']),
                ('users', usage['users']),
                ('locations', usage['locations']),
                ('recipes', usage['recipes']),
                ('suppliers', usage['suppliers']),
                ('training_jobs', usage.get('training_jobs_today', 0)),
                ('forecasts', usage.get('forecasts_today', 0)),
                ('api_calls', usage.get('api_calls_this_hour', 0)),
                ('storage', int(usage.get('file_storage_used_gb', 0))),
            ]

            for metric, value in metrics_to_track:
                await track_daily_usage(tenant.id, metric, value)

            print(f"✅ Tracked usage for tenant {tenant.id}")

        except Exception as e:
            print(f"❌ Error tracking tenant {tenant.id}: {e}")

if __name__ == "__main__":
    asyncio.run(track_all_tenants_usage())

Add to crontab:

0 0 * * * cd /path/to/bakery-ia && python services/tenant/app/cron/track_daily_usage.py

Step 3: Update Gateway Middleware

File: gateway/app/middleware/subscription.py

from app.utils.subscription_error_responses import (
    create_upgrade_required_response,
    handle_feature_restriction
)

# In your existing middleware function
async def check_subscription_access(request: Request, call_next):
    # ... existing validation code

    # If access is denied, use enhanced error response
    if not has_access:
        status_code, response_body = handle_feature_restriction(
            feature='analytics',  # Determine from route
            current_tier=subscription.tier,
            required_tier='professional'
        )

        return JSONResponse(
            status_code=status_code,
            content=response_body
        )

    # Allow access
    return await call_next(request)

---

📊 Analytics Integration

Option 1: Segment

// frontend/src/utils/subscriptionAnalytics.ts

const track = (event: string, properties: Record<string, any> = {}) => {
  // Replace console.log with Segment
  if (window.analytics) {
    window.analytics.track(event, properties);
  }

  // Keep local storage for debugging
  // ... existing code
};

Add Segment script to frontend/public/index.html:

<script>
  !function(){var analytics=window.analytics=window.analytics||[];...}();
  analytics.load("YOUR_SEGMENT_WRITE_KEY");
</script>

Option 2: Mixpanel

import mixpanel from 'mixpanel-browser';

// Initialize
mixpanel.init('YOUR_PROJECT_TOKEN');

const track = (event: string, properties: Record<string, any> = {}) => {
  mixpanel.track(event, properties);

  // Keep local storage for debugging
  // ... existing code
};

Option 3: Google Analytics 4

const track = (event: string, properties: Record<string, any> = {}) => {
  if (window.gtag) {
    window.gtag('event', event, properties);
  }

  // Keep local storage for debugging
  // ... existing code
};

---

🧪 Testing Checklist

Frontend Testing

# 1. Install dependencies (if needed)
npm install

# 2. Run type check
npm run type-check

# 3. Run linter
npm run lint

# 4. Run tests
npm test

# 5. Build for production
npm run build

# 6. Test in development
npm run dev

Backend Testing

# 1. Run Python tests
cd services/tenant
pytest app/tests/

# 2. Test usage forecast endpoint
curl -X GET "http://localhost:8000/api/v1/usage-forecast?tenant_id=test_tenant" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 3. Test usage tracking
curl -X POST "http://localhost:8000/api/v1/usage-forecast/track-usage" \
  -H "Content-Type: application/json" \
  -d '{"tenant_id": "test", "metric": "products", "value": 45}'

Manual Testing Scenarios

Scenario 1: Starter User at 90% Capacity

1. Navigate to /app/settings/subscription
2. Verify UsageMetricCard shows red progress bar
3. Verify "You'll hit limit in X days" warning appears
4. Verify upgrade CTA is visible
5. Click upgrade CTA → should navigate to upgrade flow

Scenario 2: ROI Calculator

1. As Starter user, go to subscription page
2. Scroll to ROI Calculator
3. Enter custom values (daily sales, waste %, etc.)
4. Verify calculations update in real-time
5. Verify payback period is reasonable (5-15 days)
6. Click "Upgrade to Professional" → should navigate

Scenario 3: Plan Comparison

1. Click "Compare all plans"
2. Verify table shows all 3 tiers
3. Expand/collapse categories
4. Verify Professional column is highlighted
5. Verify sparkle icons on Professional features

Scenario 4: Analytics Tracking

1. Open browser console
2. Navigate to subscription page
3. Verify analytics events in console/localStorage
4. Click various CTAs
5. Check localStorage.getItem('subscription_events')

---

🚀 Deployment Strategy

Phase 1: Staging (Week 1)

1. Deploy Frontend

   npm run build
   # Deploy to staging CDN
   

2. Deploy Backend

   # Deploy usage_forecast.py to staging tenant service
   # Deploy enhanced error responses to staging gateway
   

3. Test Everything

   • Run all manual test scenarios
   • Verify analytics tracking works
   • Test with real tenant data (anonymized)
   • Check mobile responsiveness

Phase 2: Canary Release (Week 2)

1. 10% Traffic

   • Use feature flag to show new components to 10% of users
   • Monitor analytics for any errors
   • Collect user feedback

2. Monitor KPIs

   • Track conversion rate changes
   • Monitor page load times
   • Check for JavaScript errors

3. Iterate

   • Fix any issues discovered
   • Refine based on user feedback

Phase 3: Full Rollout (Week 3)

1. 50% Traffic

   • Increase to 50% of users
   • Continue monitoring

2. 100% Traffic

   • Full rollout to all users
   • Remove feature flags
   • Announce improvements

Phase 4: Optimization (Weeks 4-8)

1. A/B Testing

   • Test different Professional tier positions
   • Test badge messaging variations
   • Test billing cycle defaults

2. Data Analysis

   • Analyze conversion funnel
   • Identify drop-off points
   • Calculate actual ROI impact

3. Iterate

   • Implement winning variants
   • Refine messaging based on data

---

📈 Success Metrics Dashboard

Create Conversion Funnel

In your analytics tool (Segment, Mixpanel, GA4):

Subscription Conversion Funnel:
1. subscription_page_viewed → 100%
2. billing_cycle_toggled → 75%
3. feature_list_expanded → 50%
4. comparison_table_viewed → 30%
5. upgrade_cta_clicked → 15%
6. upgrade_completed → 10%

Key Reports to Create

1. Conversion Rate by Tier

   • Starter → Professional: Target 12%
   • Professional → Enterprise: Track baseline

2. Time to Upgrade

   • Days from signup to first upgrade
   • Target: Reduce by 33%

3. Feature Discovery

   • % users who expand feature lists
   • Target: 50%+

4. ROI Calculator Usage

   • % Starter users who use calculator
   • Target: 40%+

5. Usage Warning Effectiveness

   • % users who upgrade after seeing warning
   • Track by metric (products, users, etc.)

---

🐛 Troubleshooting

Issue: UsageMetricCard not showing predictions

Solution: Verify Redis has usage history

redis-cli KEYS "usage:daily:*"
# Should show keys like: usage:daily:tenant_123:products:2025-11-19

Issue: ROI Calculator shows NaN values

Solution: Check input validation

// Ensure all inputs are valid numbers
const numValue = parseFloat(value) || 0;

Issue: Translation keys not working

Solution: Verify translation namespace

// Make sure you're using correct namespace
const { t } = useTranslation('subscription'); // Not 'common'

Issue: Analytics events not firing

Solution: Check analytics provider is loaded

// Add before tracking
if (!window.analytics) {
  console.error('Analytics not loaded');
  return;
}

---

📞 Support Resources

Documentation

• Implementation Guide
• Complete Summary
• This Integration Guide

Code Examples

• All components have inline documentation
• TypeScript types provide autocomplete
• Each function has JSDoc comments

Testing

• Use localStorage to debug analytics events
• Check browser console for errors
• Test with real tenant data in staging

---

✅ Pre-Launch Checklist

Frontend:

• All components compile without errors
• TypeScript has no type errors
• Linter passes (no warnings)
• All translations are complete (EN/ES/EU)
• Components tested on mobile/tablet/desktop
• Dark mode works correctly
• Analytics tracking verified

Backend:

• Usage forecast endpoint registered
• Daily cron job scheduled
• Redis keys are being created
• Error responses tested
• Rate limiting configured
• CORS headers set correctly

Analytics:

• Analytics provider connected
• Events firing in production
• Funnel created in dashboard
• Alerts configured for drop-offs

Documentation:

• Team trained on new components
• Support docs updated
• User-facing help articles created

---

Ready to launch? 🚀 Follow the deployment strategy above and monitor your metrics closely!

Last Updated: 2025-11-19