ALwrity/docs/Billing_Subscription/PRIORITY2_ALERTS_ARCHITECTURE.md

Priority 2 Alerts Architecture Explanation

Why Both Common and Tool-Specific Integrations?

You're absolutely right that common components should be updated once and automatically picked up everywhere. Here's the architecture:

Common Component Integration (UsageDashboard)

Location: frontend/src/components/shared/UsageDashboard.tsx

Used In:

• UserBadge (in HeaderControls) - appears in ALL tool headers
• WizardHeader (onboarding)
• Various tool headers directly

What It Should Show:

• ✅ Global cost trends (spending velocity, budget projections)
• ✅ Overall OSS recommendations (general cost savings opportunities)
• ✅ Usage statistics (current cost, calls, limits)

Update Once: Add Priority 2 alerts here → automatically appears in ALL tool headers

Tool-Specific Integrations (Optional)

Purpose: Contextual alerts and pre-operation cost estimation

When Needed:

1. Pre-Operation Cost Estimation: Before clicking "Generate Blog" or "Generate Image", show cost estimate
2. Contextual Recommendations: In Image Studio, recommend OSS models based on selected provider/model
3. Workflow-Specific Alerts: Blog Writer showing cost breakdown for the entire blog generation workflow

Example:

• Common: "You're spending at a high rate" (shown everywhere)
• Tool-Specific: "This blog generation will cost ~$0.05" (shown only in Blog Writer before generation)

Recommended Architecture

✅ Primary Integration: UsageDashboard

Add Priority 2 alerts to UsageDashboard.tsx:

• Shows cost trends, spending velocity, OSS recommendations
• Automatically appears in all tool headers via UserBadge/HeaderControls
• One update, everywhere

✅ Optional: Tool-Specific Hooks

Keep tool-specific hooks for:

• Pre-operation cost estimation (before expensive operations)
• Contextual recommendations (based on user's current selection)

Example Flow:

1. User opens Blog Writer
2. UsageDashboard (in header) shows: "High spending velocity detected"
3. User clicks "Generate Blog"
4. Tool-specific hook shows: "This will cost ~$0.05. Proceed?"

Implementation Plan

Phase 1: Common Integration (Recommended)

Add to UsageDashboard.tsx:

import { usePriority2Alerts } from '../../hooks/usePriority2Alerts';
import Priority2AlertBanner from '../shared/Priority2AlertBanner';

// In UsageDashboard component
const { alerts, dismissAlert } = usePriority2Alerts({
  userId,
  enabled: !!userId && subscription?.active,
});

// Show alerts above usage stats
{alerts.length > 0 && (
  <Priority2AlertBanner
    alerts={alerts}
    onDismiss={dismissAlert}
    maxAlerts={2}
  />
)}

Result: Priority 2 alerts appear in ALL tool headers automatically!

Phase 2: Tool-Specific (Optional)

Only add tool-specific integrations where you need:

• Pre-operation cost estimation
• Contextual recommendations

Example: Blog Writer

// Only for pre-operation cost estimation
const { estimateAndProceed } = useBlogWriterCostEstimation();

const handleGenerate = () => {
  estimateAndProceed('content', () => {
    // Actual generation logic
  }, userId);
};

Summary

• Common Integration: ✅ Add to UsageDashboard → appears everywhere
• Tool-Specific: ⚠️ Only for pre-operation estimation and contextual recommendations
• Best Practice: Start with common integration, add tool-specific only when needed