Base code
This commit is contained in:
Kunthawat Greethong
256
backend/test/BILLING_SYSTEM_INTEGRATION.md
Normal file
256
backend/test/BILLING_SYSTEM_INTEGRATION.md
Normal file
@@ -0,0 +1,256 @@
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# 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
|
||||
|
||||
```bash
|
||||
# Run the comprehensive verification script
|
||||
python verify_billing_setup.py
|
||||
```
|
||||
|
||||
### 3. Test API Endpoints
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
|
||||
```bash
|
||||
# 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
|
||||
```bash
|
||||
python verify_billing_setup.py
|
||||
```
|
||||
|
||||
### Test Individual Components
|
||||
```bash
|
||||
# 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!
|
||||
Reference in New Issue
Block a user