moreminimore-marketing/backend/test/BILLING_SYSTEM_INTEGRATION.md

ALwrity Billing & Subscription System Integration

Overview

The ALwrity backend now includes a comprehensive billing and subscription system that automatically tracks API usage, calculates costs, and manages subscription limits. This system is fully integrated into the startup process and provides real-time monitoring capabilities.

🚀 Quick Start

1. Start the Backend with Billing System

# From the backend directory
python start_alwrity_backend.py

The startup script will automatically:

• ✅ Create billing and subscription database tables
• ✅ Initialize default pricing and subscription plans
• ✅ Set up usage tracking middleware
• ✅ Verify all billing components are working
• ✅ Start the server with billing endpoints enabled

2. Verify Installation

# Run the comprehensive verification script
python verify_billing_setup.py

3. Test API Endpoints

# Get subscription plans
curl http://localhost:8000/api/subscription/plans

# Get user usage (replace 'demo' with actual user ID)
curl http://localhost:8000/api/subscription/usage/demo

# Get billing dashboard data
curl http://localhost:8000/api/subscription/dashboard/demo

# Get API pricing information
curl http://localhost:8000/api/subscription/pricing

📊 Database Tables

The billing system creates the following tables:

Table Name	Purpose
subscription_plans	Available subscription tiers and pricing
user_subscriptions	User subscription assignments
api_usage_logs	Detailed API usage tracking
usage_summaries	Aggregated usage statistics
api_provider_pricing	Cost per token for each AI provider
usage_alerts	Usage limit warnings and notifications
billing_history	Historical billing records

🔧 System Components

1. Database Models (models/subscription_models.py)

• SubscriptionPlan: Subscription tiers and pricing
• UserSubscription: User subscription assignments
• APIUsageLog: Detailed usage tracking
• UsageSummary: Aggregated statistics
• APIProviderPricing: Cost calculations
• UsageAlert: Limit notifications

2. Services

• PricingService (services/pricing_service.py): Cost calculations and plan management
• UsageTrackingService (services/usage_tracking_service.py): Usage monitoring and limits
• SubscriptionExceptionHandler (services/subscription_exception_handler.py): Error handling

3. API Endpoints (api/subscription_api.py)

• GET /api/subscription/plans - Available subscription plans
• GET /api/subscription/usage/{user_id} - User usage statistics
• GET /api/subscription/dashboard/{user_id} - Dashboard data
• GET /api/subscription/pricing - API pricing information
• GET /api/subscription/trends/{user_id} - Usage trends

4. Middleware Integration

• Monitoring Middleware (middleware/monitoring_middleware.py): Automatic usage tracking
• Exception Handling: Graceful error handling for billing issues

🎯 Frontend Integration

The billing system is fully integrated with the frontend dashboard:

CompactBillingDashboard

• Real-time usage metrics
• Cost tracking
• System health monitoring
• Interactive tooltips and help text

EnhancedBillingDashboard

• Detailed usage breakdowns
• Provider-specific costs
• Usage trends and analytics
• Alert management

📈 Usage Tracking

The system automatically tracks:

• API Calls: Number of requests to each provider
• Token Usage: Input and output tokens for each request
• Costs: Real-time cost calculations
• Response Times: Performance monitoring
• Error Rates: Failed request tracking
• User Activity: Per-user usage patterns

💰 Pricing Configuration

Default AI Provider Pricing (per token)

Provider	Model	Input Cost	Output Cost
OpenAI	GPT-4	$0.00003	$0.00006
OpenAI	GPT-3.5-turbo	$0.0000015	$0.000002
Gemini	Gemini Pro	$0.0000005	$0.0000015
Anthropic	Claude-3	$0.000008	$0.000024
Mistral	Mistral-7B	$0.0000002	$0.0000006

Subscription Plans

Plan	Monthly Price	Yearly Price	API Limits
Free	$0	$0	1,000 calls/month
Starter	$29	$290	10,000 calls/month
Professional	$99	$990	100,000 calls/month
Enterprise	$299	$2,990	Unlimited

🔍 Monitoring & Alerts

Real-time Monitoring

• Usage tracking for all API calls
• Cost calculations in real-time
• Performance metrics
• Error rate monitoring

Alert System

• Usage approaching limits (80% threshold)
• Cost overruns
• System health issues
• Provider-specific problems

🛠️ Development Mode

For development with auto-reload:

# Development mode with auto-reload
python start_alwrity_backend.py --dev

# Or with explicit reload flag
python start_alwrity_backend.py --reload

📝 Configuration

Environment Variables

The system uses the following environment variables:

# Database
DATABASE_URL=sqlite:///./alwrity.db

# API Keys (configured through onboarding)
OPENAI_API_KEY=your_key_here
GEMINI_API_KEY=your_key_here
ANTHROPIC_API_KEY=your_key_here
MISTRAL_API_KEY=your_key_here

# Server Configuration
HOST=0.0.0.0
PORT=8000
DEBUG=true

Custom Pricing

To modify pricing, update the PricingService.initialize_default_pricing() method in services/pricing_service.py.

🧪 Testing

Run Verification Script

python verify_billing_setup.py

Test Individual Components

# Test subscription system
python test_subscription_system.py

# Test billing tables creation
python scripts/create_billing_tables.py

🚨 Troubleshooting

Common Issues

1. Tables not created: Run python scripts/create_billing_tables.py
2. Missing dependencies: Run pip install -r requirements.txt
3. Database errors: Check DATABASE_URL in environment
4. API key issues: Verify API keys are configured

Debug Mode

Enable debug logging by setting DEBUG=true in your environment.

📚 API Documentation

Once the server is running, access the interactive API documentation:

• Swagger UI: http://localhost:8000/api/docs
• ReDoc: http://localhost:8000/api/redoc

🔄 Updates and Maintenance

Adding New Providers

1. Add provider to APIProvider enum in models/subscription_models.py
2. Update pricing in PricingService.initialize_default_pricing()
3. Add provider detection in middleware
4. Update frontend provider chips

Modifying Plans

1. Update PricingService.initialize_default_plans()
2. Modify plan limits and pricing
3. Test with verification script

📞 Support

For issues or questions:

1. Check the verification script output
2. Review the startup logs
3. Test individual components
4. Check database table creation

🎉 Success Indicators

You'll know the billing system is working when:

• ✅ Startup script shows "Billing and subscription tables created successfully"
• ✅ Verification script passes all checks
• ✅ API endpoints return data
• ✅ Frontend dashboard shows usage metrics
• ✅ Usage tracking middleware is active

The billing system is now fully integrated and ready for production use!