Skip to content

Frontend Integration Guide

Technical specifications and integration guide for implementing the billing dashboard in the ALwrity frontend.

Overview

The billing dashboard provides enterprise-grade insights and cost transparency for all external API usage. It integrates with the subscription system's backend APIs to display real-time usage, costs, and system health.

Architecture

Main Dashboard Integration Points

Main Dashboard
├── Header Section
│   ├── System Health Indicator
│   ├── Real-time Usage Summary
│   └── Alert Notifications
├── Billing Overview Section
│   ├── Current Usage vs Limits
│   ├── Cost Breakdown by Provider
│   └── Monthly Projections
├── API Monitoring Section
│   ├── External API Performance
│   ├── Cost per API Call
│   └── Usage Trends
└── Subscription Management
    ├── Plan Comparison
    ├── Usage Optimization Tips
    └── Upgrade/Downgrade Options

Service Layer

Billing Service (frontend/src/services/billingService.ts)

Core functions to implement:

export const billingService = {
  // Get comprehensive dashboard data
  getDashboardData: (userId: string) => Promise<DashboardData>

  // Get current usage statistics
  getUsageStats: (userId: string, period?: string) => Promise<UsageStats>

  // Get usage trends over time
  getUsageTrends: (userId: string, months?: number) => Promise<UsageTrends>

  // Get subscription plans
  getSubscriptionPlans: () => Promise<SubscriptionPlan[]>

  // Get API pricing information
  getAPIPricing: (provider?: string) => Promise<APIPricing[]>

  // Get usage alerts
  getUsageAlerts: (userId: string, unreadOnly?: boolean) => Promise<UsageAlert[]>

  // Mark alert as read
  markAlertRead: (alertId: number) => Promise<void>
}

Monitoring Service (frontend/src/services/monitoringService.ts)

Core functions to implement:

export const monitoringService = {
  // Get system health status
  getSystemHealth: () => Promise<SystemHealth>

  // Get API performance statistics
  getAPIStats: (minutes?: number) => Promise<APIStats>

  // Get lightweight monitoring stats
  getLightweightStats: () => Promise<LightweightStats>

  // Get cache performance metrics
  getCacheStats: () => Promise<CacheStats>
}

Type Definitions

Core Data Structures (frontend/src/types/billing.ts)

interface DashboardData {
  current_usage: UsageStats
  trends: UsageTrends
  limits: SubscriptionLimits
  alerts: UsageAlert[]
  projections: CostProjections
  summary: UsageSummary
}

interface UsageStats {
  billing_period: string
  usage_status: 'active' | 'warning' | 'limit_reached'
  total_calls: number
  total_tokens: number
  total_cost: number
  avg_response_time: number
  error_rate: number
  limits: SubscriptionLimits
  provider_breakdown: ProviderBreakdown
  alerts: UsageAlert[]
  usage_percentages: UsagePercentages
  last_updated: string
}

interface ProviderBreakdown {
  gemini: ProviderUsage
  openai: ProviderUsage
  anthropic: ProviderUsage
  mistral: ProviderUsage
  tavily: ProviderUsage
  serper: ProviderUsage
  metaphor: ProviderUsage
  firecrawl: ProviderUsage
  stability: ProviderUsage
}

interface ProviderUsage {
  calls: number
  tokens: number
  cost: number
}

Component Architecture

BillingOverview Component

File: frontend/src/components/billing/BillingOverview.tsx

Key Features: - Real-time usage display with animated counters - Progress bars for usage limits - Cost breakdown with interactive tooltips - Quick action buttons for plan management

State Management: 

const [usageData, setUsageData] = useState<UsageStats | null>(null)
const [loading, setLoading] = useState(true)
const [error, setError] = useState<string | null>(null)

CostBreakdown Component

File: frontend/src/components/billing/CostBreakdown.tsx

Key Features: - Interactive pie chart with provider breakdown - Hover effects showing detailed costs - Click to drill down into provider details - Cost per token calculations

UsageTrends Component

File: frontend/src/components/billing/UsageTrends.tsx

Key Features: - Multi-line chart showing usage over time - Toggle between cost, calls, and tokens - Trend analysis with projections - Peak usage identification

SystemHealthIndicator Component

File: frontend/src/components/monitoring/SystemHealthIndicator.tsx

Key Features: - Color-coded health status - Real-time performance metrics - Error rate monitoring - Response time tracking

Design System

Color Palette

const colors = {
  primary: {
    50: '#eff6ff',
    500: '#3b82f6',
    900: '#1e3a8a'
  },
  success: {
    50: '#f0fdf4',
    500: '#22c55e',
    900: '#14532d'
  },
  warning: {
    50: '#fffbeb',
    500: '#f59e0b',
    900: '#78350f'
  },
  danger: {
    50: '#fef2f2',
    500: '#ef4444',
    900: '#7f1d1d'
  }
}

Responsive Design

Breakpoints: - Mobile: 640px - Tablet: 768px - Desktop: 1024px - Large: 1280px

Real-Time Updates

Polling Strategy

Intelligent polling based on user activity:

const useIntelligentPolling = (userId: string) => {
  const [isActive, setIsActive] = useState(true)

  useEffect(() => {
    const interval = setInterval(() => {
      if (isActive) {
        fetchUsageData(userId)
      }
    }, isActive ? 30000 : 300000) // 30s when active, 5m when inactive

    return () => clearInterval(interval)
  }, [isActive, userId])
}

Chart Configuration

Recharts Theme

const chartTheme = {
  colors: ['#3b82f6', '#22c55e', '#f59e0b', '#ef4444', '#8b5cf6'],
  grid: {
    stroke: '#e5e7eb',
    strokeWidth: 1,
    strokeDasharray: '3 3'
  }
}

Security Implementation

API Security

Secure API calls with authentication:

const secureApiCall = async (endpoint: string, options: RequestInit = {}) => {
  const token = await getAuthToken()

  return fetch(endpoint, {
    ...options,
    headers: {
      ...options.headers,
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    }
  })
}

Performance Optimization

Code Splitting

Lazy load heavy components:

const BillingDashboard = lazy(() => import('./BillingDashboard'))
const UsageTrends = lazy(() => import('./UsageTrends'))

Memoization

Memoize expensive calculations:

const MemoizedCostBreakdown = memo(({ data }: { data: ProviderData[] }) => {
  const processedData = useMemo(() => 
    data.map(item => ({
      ...item,
      percentage: (item.cost / totalCost) * 100
    }))
  , [data, totalCost])

  return <CostBreakdownChart data={processedData} />
})

Dependencies

Required packages:

npm install recharts framer-motion lucide-react
npm install @tanstack/react-query axios
npm install zod

Integration Status

✅ Completed

  • Type definitions and validation schemas
  • Service layer with all API functions
  • Core components (BillingOverview, CostBreakdown, UsageTrends, UsageAlerts)
  • SystemHealthIndicator component
  • Main dashboard integration
  • Real-time data fetching with auto-refresh

🔄 Ready for Enhancement

  • WebSocket integration for instant updates
  • Advanced analytics and optimization suggestions
  • Export functionality for reports
  • Mobile app optimization

Next Steps

Last Updated: January 2025