kunthawat/moreminimore-marketing
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Base code

Browse Source
This commit is contained in:
Kunthawat Greethong
2026-01-08 22:39:53 +07:00
parent 697115c61a
commit c35fa52117
2169 changed files with 626670 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

445
docs-site/docs/features/subscription/api-reference.md Normal file
View File

@@ -0,0 +1,445 @@
# Subscription API Reference
Complete API endpoint documentation for the ALwrity subscription system.
## Base URL
All endpoints are prefixed with `/api/subscription`
## Authentication
All endpoints require user authentication. Include the user ID in the request path or headers as appropriate.
## Subscription Management Endpoints
### Get All Subscription Plans
Get a list of all available subscription plans.
```http
GET /api/subscription/plans
```
**Response:**
```json
{
"success": true,
"data": [
{
"id": 1,
"name": "Free",
"price": 0.0,
"billing_cycle": "monthly",
"limits": {
"gemini_calls": 100,
"tokens": 100000
}
},
{
"id": 2,
"name": "Basic",
"price": 29.0,
"billing_cycle": "monthly",
"limits": {
"gemini_calls": 1000,
"openai_calls": 500,
"tokens": 1500000,
"monthly_cost": 50.0
}
}
]
}
```
### Get User Subscription
Get the current subscription details for a specific user.
```http
GET /api/subscription/user/{user_id}/subscription
```
**Parameters:**
- `user_id` (path): The user's unique identifier
**Response:**
```json
{
"success": true,
"data": {
"user_id": "user123",
"plan_name": "Pro",
"plan_id": 3,
"status": "active",
"started_at": "2025-01-01T00:00:00Z",
"expires_at": "2025-02-01T00:00:00Z",
"limits": {
"gemini_calls": 5000,
"openai_calls": 2500,
"monthly_cost": 150.0
}
}
}
```
### Get API Pricing Information
Get current pricing configuration for all API providers.
```http
GET /api/subscription/pricing
```
**Response:**
```json
{
"success": true,
"data": [
{
"provider": "gemini",
"model": "gemini-2.5-flash",
"input_cost_per_1m": 0.125,
"output_cost_per_1m": 0.375
},
{
"provider": "tavily",
"cost_per_request": 0.001
}
]
}
```
## Usage Tracking Endpoints
### Get Current Usage Statistics
Get current usage statistics for a user.
```http
GET /api/subscription/usage/{user_id}
```
**Parameters:**
- `user_id` (path): The user's unique identifier
**Response:**
```json
{
"success": true,
"data": {
"billing_period": "2025-01",
"total_calls": 1250,
"total_tokens": 210000,
"total_cost": 15.75,
"usage_status": "active",
"limits": {
"gemini_calls": 5000,
"monthly_cost": 150.0
},
"provider_breakdown": {
"gemini": {
"calls": 800,
"tokens": 125000,
"cost": 10.50
},
"openai": {
"calls": 450,
"tokens": 85000,
"cost": 5.25
}
},
"usage_percentages": {
"gemini_calls": 16.0,
"cost": 10.5
}
}
}
```
### Get Usage Trends
Get historical usage trends over time.
```http
GET /api/subscription/usage/{user_id}/trends?months=6
```
**Parameters:**
- `user_id` (path): The user's unique identifier
- `months` (query, optional): Number of months to retrieve (default: 6)
**Response:**
```json
{
"success": true,
"data": {
"periods": [
{
"period": "2024-07",
"total_calls": 850,
"total_cost": 12.50,
"provider_breakdown": {
"gemini": {"calls": 600, "cost": 8.00},
"openai": {"calls": 250, "cost": 4.50}
}
}
],
"trends": {
"calls_trend": "increasing",
"cost_trend": "stable"
}
}
}
```
### Get Dashboard Data
Get comprehensive dashboard data including usage, limits, projections, and alerts.
```http
GET /api/subscription/dashboard/{user_id}
```
**Parameters:**
- `user_id` (path): The user's unique identifier
**Response:**
```json
{
"success": true,
"data": {
"summary": {
"total_api_calls_this_month": 1250,
"total_cost_this_month": 15.75,
"usage_status": "active",
"unread_alerts": 2
},
"current_usage": {
"billing_period": "2025-01",
"total_calls": 1250,
"total_cost": 15.75,
"usage_status": "active",
"provider_breakdown": {
"gemini": {"calls": 800, "cost": 10.50, "tokens": 125000},
"openai": {"calls": 450, "cost": 5.25, "tokens": 85000}
},
"usage_percentages": {
"gemini_calls": 16.0,
"openai_calls": 18.0,
"cost": 10.5
}
},
"limits": {
"plan_name": "Pro",
"limits": {
"gemini_calls": 5000,
"openai_calls": 2500,
"monthly_cost": 150.0
}
},
"projections": {
"projected_monthly_cost": 47.25,
"projected_usage_percentage": 31.5
},
"alerts": [
{
"id": 1,
"title": "API Usage Notice - Gemini",
"message": "You have used 800 of 5,000 Gemini API calls",
"severity": "info",
"created_at": "2025-01-15T10:30:00Z",
"read": false
}
]
}
}
```
## Alerts & Notifications Endpoints
### Get Usage Alerts
Get usage alerts and notifications for a user.
```http
GET /api/subscription/alerts/{user_id}?unread_only=false
```
**Parameters:**
- `user_id` (path): The user's unique identifier
- `unread_only` (query, optional): Filter to only unread alerts (default: false)
**Response:**
```json
{
"success": true,
"data": [
{
"id": 1,
"user_id": "user123",
"title": "API Usage Notice - Gemini",
"message": "You have used 800 of 5,000 Gemini API calls",
"severity": "info",
"alert_type": "usage_threshold",
"created_at": "2025-01-15T10:30:00Z",
"read": false
},
{
"id": 2,
"user_id": "user123",
"title": "Usage Warning",
"message": "You have reached 90% of your monthly cost limit",
"severity": "warning",
"alert_type": "cost_threshold",
"created_at": "2025-01-20T14:15:00Z",
"read": false
}
]
}
```
### Mark Alert as Read
Mark a specific alert as read.
```http
POST /api/subscription/alerts/{alert_id}/mark-read
```
**Parameters:**
- `alert_id` (path): The alert's unique identifier
**Response:**
```json
{
"success": true,
"message": "Alert marked as read"
}
```
## Usage Examples
### Get User Usage (cURL)
```bash
curl -X GET "http://localhost:8000/api/subscription/usage/user123" \
-H "Content-Type: application/json"
```
### Get Dashboard Data (cURL)
```bash
curl -X GET "http://localhost:8000/api/subscription/dashboard/user123" \
-H "Content-Type: application/json"
```
### Get Usage Trends (cURL)
```bash
curl -X GET "http://localhost:8000/api/subscription/usage/user123/trends?months=6" \
-H "Content-Type: application/json"
```
### JavaScript Example
```javascript
// Get comprehensive usage data
const response = await fetch(`/api/subscription/dashboard/${userId}`);
const data = await response.json();
console.log(data.data.summary);
// {
// total_api_calls_this_month: 1250,
// total_cost_this_month: 15.75,
// usage_status: "active",
// unread_alerts: 2
// }
// Get current usage percentages
const usage = data.data.current_usage;
console.log(usage.usage_percentages);
// {
// gemini_calls: 16.0,
// openai_calls: 18.0,
// cost: 10.5
// }
```
### Python Example
```python
import requests
# Get user usage statistics
response = requests.get(
f"http://localhost:8000/api/subscription/usage/{user_id}",
headers={"Content-Type": "application/json"}
)
data = response.json()
usage = data["data"]
print(f"Total calls: {usage['total_calls']}")
print(f"Total cost: ${usage['total_cost']}")
print(f"Status: {usage['usage_status']}")
```
## Error Responses
All endpoints return consistent error responses:
```json
{
"success": false,
"error": "error_type",
"message": "Human-readable error message",
"details": "Additional error details",
"user_id": "user123",
"timestamp": "2025-01-15T10:30:00Z"
}
```
### Common Error Codes
- `400 Bad Request`: Invalid request parameters
- `401 Unauthorized`: Authentication required
- `404 Not Found`: Resource not found
- `429 Too Many Requests`: Usage limit exceeded
- `500 Internal Server Error`: Server error
## Rate Limiting
Usage limits are enforced automatically. When a limit is exceeded, the API returns a `429 Too Many Requests` response:
```json
{
"success": false,
"error": "UsageLimitExceededException",
"message": "Usage limit exceeded for Gemini API calls",
"details": {
"provider": "gemini",
"limit_type": "api_calls",
"current_usage": 1000,
"limit_value": 1000
}
}
```
## Next Steps
- [Overview](overview.md) - System architecture and features
- [Setup](setup.md) - Installation and configuration
- [Pricing](pricing.md) - Subscription plans and API pricing
---
**Last Updated**: January 2025

339
docs-site/docs/features/subscription/frontend-integration.md Normal file
View File

@@ -0,0 +1,339 @@
# 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:
```typescript
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:
```typescript
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`)
```typescript
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**:
```typescript
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
```typescript
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:
```typescript
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
```typescript
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:
```typescript
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:
```typescript
const BillingDashboard = lazy(() => import('./BillingDashboard'))
const UsageTrends = lazy(() => import('./UsageTrends'))
```
### Memoization
Memoize expensive calculations:
```typescript
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:
```bash
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
- [API Reference](api-reference.md) - Backend endpoint documentation
- [Implementation Status](implementation-status.md) - Current features and metrics
- [Roadmap](roadmap.md) - Future enhancements
---
**Last Updated**: January 2025

267
docs-site/docs/features/subscription/implementation-status.md Normal file
View File

@@ -0,0 +1,267 @@
# Implementation Status
Current status of the ALwrity usage-based subscription system implementation.
## Overall Progress
**Phase 1 Complete** - Core billing dashboard integrated and functional
## Completed Components
### Backend Integration (100% Complete)
- **Database Setup**: ✅ All subscription tables created and initialized
- **API Integration**: ✅ All subscription routes integrated in `app.py`
- **Middleware Integration**: ✅ Enhanced monitoring middleware with usage tracking
- **Critical Issues Fixed**: ✅ All identified issues resolved:
- Fixed `billing_history` table detection in test suite
- Resolved `NoneType + int` error in usage tracking service
- Fixed middleware double request body consumption
### Frontend Foundation (100% Complete)
- **Dependencies**: ✅ All required packages installed
- `recharts` - Data visualization
- `framer-motion` - Animations
- `lucide-react` - Icons
- `@tanstack/react-query` - API caching
- `axios` - HTTP client
- `zod` - Type validation
### Type System (100% Complete)
- **File**: `frontend/src/types/billing.ts`
- **Interfaces**: ✅ All core interfaces defined
- `DashboardData`, `UsageStats`, `ProviderBreakdown`
- `SubscriptionLimits`, `UsageAlert`, `CostProjections`
- `UsageTrends`, `APIPricing`, `SubscriptionPlan`
- **Zod Schemas**: ✅ All validation schemas implemented
- **Type Safety**: ✅ Full TypeScript coverage with runtime validation
### Service Layer (100% Complete)
- **File**: `frontend/src/services/billingService.ts`
- **API Functions**: ✅ All core functions implemented
- `getDashboardData()`, `getUsageStats()`, `getUsageTrends()`
- `getSubscriptionPlans()`, `getAPIPricing()`, `getUsageAlerts()`
- `markAlertRead()`, `getUserSubscription()`
- **Error Handling**: ✅ Comprehensive error handling and retry logic
- **Data Coercion**: ✅ Raw API response sanitization and validation
- **File**: `frontend/src/services/monitoringService.ts`
- **Monitoring Functions**: ✅ All monitoring APIs integrated
- `getSystemHealth()`, `getAPIStats()`, `getLightweightStats()`, `getCacheStats()`
### Core Components (100% Complete)
- **File**: `frontend/src/components/billing/BillingDashboard.tsx`
- ✅ Main container component with real-time data fetching
- ✅ Loading states and error handling
- ✅ Auto-refresh every 30 seconds
- ✅ Responsive design
- **File**: `frontend/src/components/billing/BillingOverview.tsx`
- ✅ Usage metrics display with animated counters
- ✅ Progress bars for usage limits
- ✅ Status indicators (active/warning/limit_reached)
- ✅ Quick action buttons
- **File**: `frontend/src/components/billing/CostBreakdown.tsx`
- ✅ Interactive pie chart with provider breakdown
- ✅ Hover effects and detailed cost information
- ✅ Provider-specific cost analysis
- ✅ Responsive chart sizing
- **File**: `frontend/src/components/billing/UsageTrends.tsx`
- ✅ Multi-line chart for usage trends over time
- ✅ Time range selector (3m, 6m, 12m)
- ✅ Metric toggle (cost/calls/tokens)
- ✅ Trend analysis and projections
- **File**: `frontend/src/components/billing/UsageAlerts.tsx`
- ✅ Alert management interface
- ✅ Severity-based color coding
- ✅ Read/unread status management
- ✅ Alert filtering and actions
- **File**: `frontend/src/components/monitoring/SystemHealthIndicator.tsx`
- ✅ Real-time system status display
- ✅ Color-coded health indicators
- ✅ Performance metrics (response time, error rate, uptime)
- ✅ Auto-refresh capabilities
### Main Dashboard Integration (100% Complete)
- **File**: `frontend/src/components/MainDashboard/MainDashboard.tsx`
- ✅ `BillingDashboard` component integrated
- ✅ Positioned after `AnalyticsInsights` as requested
- ✅ Seamless integration with existing dashboard layout
### Build System (100% Complete)
- **TypeScript Compilation**: ✅ All type errors resolved
- **Schema Validation**: ✅ Zod schemas properly ordered and validated
- **Import Resolution**: ✅ All module imports working correctly
- **Production Build**: ✅ Successful build with optimized bundle
## Current Features
### Real-Time Monitoring
- ✅ Live usage tracking with 30-second refresh
- ✅ System health monitoring with color-coded status
- ✅ API performance metrics (response time, error rate)
- ✅ Cost tracking across all external APIs
### Cost Transparency
- ✅ Detailed cost breakdown by provider (Gemini, OpenAI, Anthropic, etc.)
- ✅ Interactive pie charts with hover details
- ✅ Usage trends with 6-month historical data
- ✅ Monthly cost projections and alerts
### User Experience
- ✅ Enterprise-grade design with Tailwind CSS
- ✅ Smooth animations with Framer Motion
- ✅ Responsive design (mobile, tablet, desktop)
- ✅ Loading states and error handling
- ✅ Intuitive navigation and interactions
### Data Visualization
- ✅ Interactive charts with Recharts
- ✅ Provider cost breakdown (pie charts)
- ✅ Usage trends over time (line charts)
- ✅ Progress bars for usage limits
- ✅ Status indicators with color coding
## Implementation Metrics
### Code Quality
- **TypeScript Coverage**: 100% - All components fully typed
- **Build Status**: ✅ Successful - No compilation errors
- **Linting**: ⚠️ Minor warnings (unused imports) - Non-blocking
- **Bundle Size**: 1.12 MB (within acceptable range)
### Component Architecture
- **Total Components**: 6 billing + 1 monitoring = 7 components
- **Service Functions**: 12 billing + 4 monitoring = 16 API functions
- **Type Definitions**: 15+ interfaces with full Zod validation
- **Integration Points**: 1 main dashboard integration
### API Integration
- **Backend Endpoints**: 8 subscription + 4 monitoring = 12 endpoints
- **Error Handling**: Comprehensive with retry logic
- **Data Validation**: Runtime validation with Zod schemas
- **Caching**: React Query for intelligent data caching
## Delivered Components
### Database Models
- **SubscriptionPlan**: Defines subscription tiers (Free, Basic, Pro, Enterprise)
- **UserSubscription**: Tracks user subscription details and billing
- **APIUsageLog**: Detailed logging of every API call with cost tracking
- **UsageSummary**: Aggregated usage statistics per user per billing period
- **APIProviderPricing**: Configurable pricing for all API providers
- **UsageAlert**: Automated alerts for usage thresholds
- **BillingHistory**: Historical billing records
### Core Services
- **Pricing Service**: Real-time cost calculation for all API providers
- **Usage Tracking Service**: Comprehensive API usage tracking
- **Exception Handler**: Robust error handling with detailed logging
- **Enhanced Middleware**: Automatic API provider detection and usage tracking
### API Endpoints
- `GET /api/subscription/plans` - Available subscription plans
- `GET /api/subscription/usage/{user_id}` - Current usage statistics
- `GET /api/subscription/usage/{user_id}/trends` - Usage trends over time
- `GET /api/subscription/dashboard/{user_id}` - Comprehensive dashboard data
- `GET /api/subscription/pricing` - API pricing information
- `GET /api/subscription/alerts/{user_id}` - Usage alerts and notifications
## Success Criteria Met
### ✅ Functional Requirements
- [x] Real-time usage monitoring
- [x] Cost transparency and breakdown
- [x] System health monitoring
- [x] Usage alerts and notifications
- [x] Responsive design
- [x] Enterprise-grade UI/UX
### ✅ Technical Requirements
- [x] TypeScript type safety
- [x] Runtime data validation
- [x] Error handling and recovery
- [x] Performance optimization
- [x] Code maintainability
- [x] Integration with existing system
### ✅ User Experience Requirements
- [x] Intuitive navigation
- [x] Clear cost explanations
- [x] Real-time updates
- [x] Mobile responsiveness
- [x] Professional design
- [x] Smooth animations
## Business Impact
### Cost Transparency
- **Before**: Users had no visibility into API costs
- **After**: Complete cost breakdown with real-time tracking
- **Impact**: Reduced surprise overages, better cost awareness
### System Monitoring
- **Before**: Limited system health visibility
- **After**: Real-time monitoring with performance metrics
- **Impact**: Proactive issue detection, improved reliability
### User Experience
- **Before**: Basic dashboard with limited insights
- **After**: Enterprise-grade billing dashboard with advanced analytics
- **Impact**: Professional appearance, increased user confidence
## Next Steps
### Phase 2: Advanced Features (Optional)
1. **Real-Time WebSocket Integration**
- WebSocket connection for instant updates
- Push notifications for usage alerts
- Live cost tracking during API calls
2. **Advanced Analytics**
- Cost optimization suggestions
- Usage pattern analysis
- Predictive cost modeling
- Provider performance comparison
3. **Enhanced User Experience**
- Interactive tooltips with detailed explanations
- Advanced filtering and sorting options
- Export functionality for reports
- Mobile app optimization
4. **Subscription Management**
- Plan comparison and upgrade flows
- Billing history and invoice management
- Payment method management
- Usage-based plan recommendations
## Conclusion
The billing and subscription implementation is **100% complete** for Phase 1, successfully delivering:
1. **Complete Backend Integration** - All APIs, databases, and middleware working
2. **Full Frontend Implementation** - All components built and integrated
3. **Enterprise-Grade Design** - Professional UI with smooth animations
4. **Real-Time Monitoring** - Live usage tracking and system health
5. **Cost Transparency** - Detailed breakdowns and trend analysis
6. **Production Ready** - Successful build with no critical issues
The system is now ready for production deployment and provides users with comprehensive visibility into their API usage, costs, and system performance.
---
**Last Updated**: January 2025
**Status**: ✅ Production Ready
**Next Review**: Optional Phase 2 enhancements

157
docs-site/docs/features/subscription/overview.md Normal file
View File

@@ -0,0 +1,157 @@
# Subscription System Overview
ALwrity's usage-based subscription system provides comprehensive API cost tracking, usage limits, and real-time monitoring for all external API providers.
## Features
### Core Functionality
- **Usage-Based Billing**: Track API calls, tokens, and costs across all providers
- **Subscription Tiers**: Free, Basic, Pro, and Enterprise plans with different limits
- **Real-Time Monitoring**: Live usage tracking and limit enforcement
- **Cost Calculation**: Accurate pricing for Gemini, OpenAI, Anthropic, and other APIs
- **Usage Alerts**: Automatic notifications at 80%, 90%, and 100% usage thresholds
- **Robust Error Handling**: Comprehensive logging and exception management
### Supported API Providers
- **Gemini API**: Google's AI models with latest pricing
- **OpenAI**: GPT models and embeddings
- **Anthropic**: Claude models
- **Mistral AI**: Mistral models
- **Tavily**: AI-powered search
- **Serper**: Google search API
- **Metaphor/Exa**: Advanced search
- **Firecrawl**: Web content extraction
- **Stability AI**: Image generation
- **Hugging Face**: GPT-OSS-120B via Groq
## Architecture
### Database Schema
The system uses the following core tables:
- `subscription_plans`: Available subscription tiers and limits
- `user_subscriptions`: User subscription information
- `api_usage_logs`: Detailed log of every API call
- `usage_summaries`: Aggregated usage per user per billing period
- `api_provider_pricing`: Pricing configuration for all providers
- `usage_alerts`: Usage notifications and warnings
- `billing_history`: Historical billing records
### Service Structure
```
backend/services/subscription/
├── __init__.py # Package exports
├── pricing_service.py # API pricing and cost calculations
├── usage_tracking_service.py # Usage tracking and limits
├── exception_handler.py # Exception handling
└── monitoring_middleware.py # API monitoring middleware
```
### Core Services
#### Pricing Service
- Real-time cost calculation for all API providers
- Subscription limit management
- Usage validation and enforcement
- Support for Gemini, OpenAI, Anthropic, Mistral, and search APIs
#### Usage Tracking Service
- Comprehensive API usage tracking
- Real-time usage statistics
- Trend analysis and projections
- Automatic alert generation at 80%, 90%, and 100% thresholds
#### Exception Handler
- Robust error handling with detailed logging
- Structured exception types for different scenarios
- Automatic alert creation for critical errors
- User-friendly error messages
### Enhanced Middleware
The system automatically tracks API usage through enhanced middleware:
- **Automatic API Provider Detection**: Identifies Gemini, OpenAI, Anthropic, etc.
- **Token Estimation**: Estimates usage from request/response content
- **Pre-Request Validation**: Enforces usage limits before processing
- **Cost Tracking**: Real-time cost calculation and logging
- **Usage Limit Enforcement**: Returns 429 errors when limits exceeded
## Key Capabilities
### Usage-Based Billing
- ✅ **Real-time cost tracking** for all API providers
- ✅ **Token-level precision** for LLM APIs (Gemini, OpenAI, Anthropic)
- ✅ **Request-based pricing** for search APIs (Tavily, Serper, Metaphor)
- ✅ **Automatic cost calculation** with configurable pricing
### Subscription Management
- ✅ **4 Subscription Tiers**: Free, Basic ($29/mo), Pro ($79/mo), Enterprise ($199/mo)
- ✅ **Flexible limits**: API calls, tokens, and monthly cost caps
- ✅ **Usage enforcement**: Pre-request validation and blocking
- ✅ **Billing cycle support**: Monthly and yearly options
### Monitoring & Analytics
- ✅ **Real-time dashboard** with usage statistics
- ✅ **Usage trends** and projections
- ✅ **Provider-specific breakdowns** (Gemini, OpenAI, etc.)
- ✅ **Performance metrics** (response times, error rates)
### Alert System
- ✅ **Automatic notifications** at 80%, 90%, and 100% usage
- ✅ **Multi-channel alerts** (database, logs, future email integration)
- ✅ **Alert management** (mark as read, severity levels)
- ✅ **Usage recommendations** and upgrade prompts
## Security & Privacy
### Data Protection
- User usage data is encrypted at rest
- API keys are never logged in usage tracking
- Sensitive information is excluded from error logs
- GDPR-compliant data handling
### Rate Limiting
- Pre-request usage validation
- Automatic limit enforcement
- Graceful degradation when limits are reached
- User-friendly error messages
## Exception Types
The system uses structured exception types:
- `UsageLimitExceededException`: When usage limits are reached
- `PricingException`: Pricing calculation errors
- `TrackingException`: Usage tracking failures
- `SubscriptionException`: General subscription errors
## Customization
### Adding New API Providers
1. Add provider to `APIProvider` enum
2. Configure pricing in `api_provider_pricing` table
3. Update detection patterns in middleware
4. Add usage tracking logic
### Modifying Subscription Plans
1. Update plans in database or via API
2. Modify limits and pricing
3. Add/remove features
4. Update billing integration
## Next Steps
- [Setup Guide](setup.md) - Installation and configuration
- [API Reference](api-reference.md) - Endpoint documentation
- [Pricing](pricing.md) - Subscription plans and API pricing
- [Frontend Integration](frontend-integration.md) - Technical specifications
- [Implementation Status](implementation-status.md) - Current features and metrics
---
**Version**: 1.0.0
**Last Updated**: January 2025

98
docs-site/docs/features/subscription/pricing.md Normal file
View File

@@ -0,0 +1,98 @@
# Subscription Plans & API Pricing
End-to-end reference for ALwrity's usage-based subscription tiers, API cost configuration, and plan-specific limits. All data is sourced from `backend/services/subscription/pricing_service.py`.
## Subscription Plans
> **Legend**: `∞` = Unlimited. Limits reset at the start of each billing cycle.
| Plan | Price (Monthly / Yearly) | AI Text Generation Calls* | Token Limits (per provider) | Key API Limits | Video Generation | Monthly Cost Cap | Highlights |
| --- | --- | --- | --- | --- | --- | --- | --- |
| **Free** | `$0 / $0` | 100 Gemini • 50 Mistral (legacy enforcement) | 100K Gemini tokens | 20 Tavily • 20 Serper • 10 Metaphor • 10 Firecrawl • 5 Stability • 100 Exa | Not included | `$0` | Basic content generation & limited research |
| **Basic** | `$29 / $290` | **10 unified LLM calls** (Gemini + OpenAI + Anthropic + Mistral combined) | 20K tokens each (Gemini, OpenAI, Anthropic, Mistral) | 200 Tavily • 200 Serper • 100 Metaphor • 100 Firecrawl • 5 Stability • 500 Exa | 20 videos/mo | `$50` | Full content generation, advanced research, basic analytics |
| **Pro** | `$79 / $790` | 5K Gemini • 2.5K OpenAI • 1K Anthropic • 2.5K Mistral | 5M Gemini • 2.5M OpenAI • 1M Anthropic • 2.5M Mistral | 1K Tavily • 1K Serper • 500 Metaphor • 500 Firecrawl • 200 Stability • 2K Exa | 50 videos/mo | `$150` | Premium research, advanced analytics, priority support |
| **Enterprise** | `$199 / $1,990` | ∞ across all LLM providers | ∞ | ∞ across every research/media API | ∞ | `$500` | White-label, dedicated support, custom integrations |
\*The Basic plan now enforces a **unified** `ai_text_generation_calls_limit` of 10 requests across all LLM providers. Legacy per-provider columns remain for analytics dashboards but do not control enforcement.
### Plan Feature Notes
- **Video Generation**: Powered by Hugging Face `tencent/HunyuanVideo` ($0.10 per request). Plan limits are shown above.
- **Image Generation**: Stability AI billed at $0.04/image. Limits shown under “Key API Limits”.
- **Research APIs**: Tavily, Serper, Metaphor, Exa, and Firecrawl are individually rate-limited per plan.
- **Cost Caps**: `monthly_cost_limit` hard stops spend at $50 / $150 / $500 for paid tiers. Enterprise caps are adjustable via support.
## Provider Pricing Matrix
### Gemini 2.5 & 1.5 (Google)
- `gemini-2.5-pro` — $0.00000125 input / $0.00001 output per token ($1.25 / $10 per 1M tokens)
- `gemini-2.5-pro-large` — $0.0000025 / $0.000015 per token (large context)
- `gemini-2.5-flash` — $0.0000003 / $0.0000025 per token
- `gemini-2.5-flash-audio` — $0.000001 / $0.0000025 per token
- `gemini-2.5-flash-lite` — $0.0000001 / $0.0000004 per token
- `gemini-2.5-flash-lite-audio` — $0.0000003 / $0.0000004 per token
- `gemini-1.5-flash` — $0.000000075 / $0.0000003 per token
- `gemini-1.5-flash-8b` — $0.0000000375 / $0.00000015 per token
- `gemini-1.5-pro` — $0.00000125 / $0.000005 per token
- `gemini-1.5-pro-large` — $0.0000025 / $0.00001 per token
- `gemini-embedding` — $0.00000015 per input token
- `gemini-grounding-search` — $35 per 1,000 requests after the free tier
### OpenAI (estimates — update when official pricing changes)
- `gpt-4o` — $0.0000025 input / $0.00001 output per token
- `gpt-4o-mini` — $0.00000015 input / $0.0000006 output per token
### Anthropic
- `claude-3.5-sonnet` — $0.000003 input / $0.000015 output per token
### Hugging Face / Mistral (GPT-OSS-120B via Groq)
Pricing is configurable through environment variables:
```
HUGGINGFACE_INPUT_TOKEN_COST=0.000001 # $1 per 1M tokens
HUGGINGFACE_OUTPUT_TOKEN_COST=0.000003 # $3 per 1M tokens
```
Models covered: `openai/gpt-oss-120b:groq`, `gpt-oss-120b`, and `default` (fallback).
### Search, Image, and Video APIs
- Tavily — $0.001 per search
- Serper — $0.001 per search
- Metaphor — $0.003 per search
- Exa — $0.005 per search (1–25 results)
- Firecrawl — $0.002 per crawled page
- Stability AI — $0.04 per image
- Video Generation (HunyuanVideo) — $0.10 per video request
## Updating Pricing & Plans
1. **Initial Seed** — `python backend/scripts/create_subscription_tables.py` creates plans and pricing.
2. **Env Overrides** — Hugging Face pricing refreshes from `HUGGINGFACE_*` vars every boot.
3. **Scripts & Maintenance** — Use `backend/scripts/` utilities (e.g., `update_basic_plan_limits.py`, `cap_basic_plan_usage.py`) to roll forward changes.
4. **Direct DB Edits** — Modify `subscription_plans` or `api_provider_pricing` tables for emergency adjustments.
## Cost Examples
| Scenario | Calculation | Cost |
| --- | --- | --- |
| Gemini 2.5 Flash (1K input / 500 output tokens) | (1,000 × 0.0000003) + (500 × 0.0000025) | **$0.00155** |
| Tavily Search | 1 request × $0.001 | **$0.001** |
| Hugging Face GPT-OSS-120B (2K in / 1K out) | (2,000 × 0.000001) + (1,000 × 0.000003) | **$0.005** |
| Video Generation (Basic plan) | 1 request × $0.10 | **$0.10** (counts toward 20-video quota) |
## Enforcement & Monitoring
1. Middleware estimates usage and calls `UsageTrackingService.track_api_usage`.
2. `UsageService.enforce_usage_limits` validates the request before the downstream provider call.
3. When a limit would be exceeded, the API returns `429` with upgrade guidance.
4. The Billing Dashboard (`/billing`) shows real-time usage, cost projections, provider breakdowns, renewal history, and usage logs.
## Additional Resources
- [Billing Dashboard](billing-dashboard.md)
- [API Reference](api-reference.md)
- [Setup Guide](setup.md)
- [Gemini Pricing](https://ai.google.dev/gemini-api/docs/pricing)
- [OpenAI Pricing](https://openai.com/pricing)
---
**Last Updated**: November 2025

232
docs-site/docs/features/subscription/roadmap.md Normal file
View File

@@ -0,0 +1,232 @@
# Subscription System Roadmap
Implementation phases and future enhancements for the ALwrity subscription system.
## Phase 1: Foundation & Core Components ✅ Complete
**Status**: ✅ **100% Complete**
### Completed Deliverables
#### Project Setup & Dependencies
- ✅ Installed required packages (recharts, framer-motion, lucide-react, react-query, axios, zod)
- ✅ Created folder structure for billing and monitoring components
#### Type Definitions
- ✅ Defined core interfaces (DashboardData, UsageStats, ProviderBreakdown, etc.)
- ✅ Created validation schemas with Zod
- ✅ Exported all type definitions
#### Service Layer
- ✅ Implemented billing service with all API client functions
- ✅ Implemented monitoring service with monitoring API functions
- ✅ Added error handling and retry logic
- ✅ Implemented request/response interceptors
#### Core Components
- ✅ BillingOverview component with usage metrics
- ✅ SystemHealthIndicator component with health status
- ✅ CostBreakdown component with interactive charts
- ✅ UsageTrends component with time range selection
- ✅ UsageAlerts component with alert management
- ✅ BillingDashboard main container component
#### Dashboard Integration
- ✅ Integrated BillingDashboard into MainDashboard
- ✅ Added responsive grid layout
- ✅ Implemented section navigation
## Phase 2: Data Visualization & Charts ✅ Complete
**Status**: ✅ **100% Complete**
### Completed Deliverables
#### Chart Components
- ✅ Implemented pie chart with Recharts for cost breakdown
- ✅ Added interactive tooltips and provider legend
- ✅ Created line chart for usage trends
- ✅ Implemented metric toggle (cost/calls/tokens)
- ✅ Added trend analysis display
#### Dashboard Integration
- ✅ Enhanced dashboard header with system health indicator
- ✅ Added usage summary and alert notification badge
- ✅ Created billing section wrapper
- ✅ Implemented responsive grid layout
## Phase 3: Real-Time Updates & Animations ✅ Complete
**Status**: ✅ **100% Complete**
### Completed Deliverables
#### Real-Time Updates
- ✅ Implemented intelligent polling (30s when active, 5m when inactive)
- ✅ Added auto-refresh capabilities
- ✅ Implemented loading states and error handling
#### Animations
- ✅ Added Framer Motion animations for page transitions
- ✅ Implemented card hover effects
- ✅ Added number animations for metrics
- ✅ Created skeleton loaders for loading states
#### Responsive Design
- ✅ Implemented mobile-first responsive design
- ✅ Added breakpoint-specific layouts
- ✅ Optimized chart sizing for different screen sizes
## Phase 4: Advanced Features & Optimization 🔄 Optional
**Status**: 🔄 **Future Enhancements**
### Planned Features
#### Real-Time WebSocket Integration
- [ ] WebSocket connection for instant updates
- [ ] Push notifications for usage alerts
- [ ] Live cost tracking during API calls
- [ ] Real-time dashboard updates without polling
#### Advanced Analytics
- [ ] Cost optimization suggestions
- [ ] Usage pattern analysis
- [ ] Predictive cost modeling
- [ ] Provider performance comparison
- [ ] Anomaly detection for unusual usage patterns
#### Enhanced User Experience
- [ ] Interactive tooltips with detailed explanations
- [ ] Advanced filtering and sorting options
- [ ] Export functionality for reports (PDF, CSV)
- [ ] Mobile app optimization
- [ ] Dark mode support
- [ ] Customizable dashboard layouts
#### Subscription Management
- [ ] Plan comparison interface
- [ ] Upgrade/downgrade flows
- [ ] Billing history and invoice management
- [ ] Payment method management
- [ ] Usage-based plan recommendations
- [ ] Automatic plan suggestions based on usage
#### Performance Optimizations
- [ ] Code splitting for large components
- [ ] Lazy loading for chart components
- [ ] Data pagination for large datasets
- [ ] Memoization for expensive calculations
- [ ] Virtual scrolling for long lists
## Phase 5: Enterprise Features 🚀 Future
**Status**: 🚀 **Long-Term Roadmap**
### Planned Enterprise Features
#### Multi-Tenant Support
- [ ] Organization-level usage tracking
- [ ] Team usage allocation and limits
- [ ] Department-level cost allocation
- [ ] Budget management per team/department
#### Advanced Reporting
- [ ] Custom report builder
- [ ] Scheduled report generation
- [ ] Email report delivery
- [ ] Executive dashboards
- [ ] Cost forecasting and budgeting
#### Integration Enhancements
- [ ] Slack/Teams notifications
- [ ] Webhook support for external integrations
- [ ] API for third-party billing systems
- [ ] SSO integration for enterprise customers
- [ ] Audit log and compliance reporting
#### Advanced Monitoring
- [ ] Custom alert rules
- [ ] Alert escalation policies
- [ ] Performance SLA tracking
- [ ] Provider health monitoring
- [ ] Cost anomaly detection
## Technical Debt & Optimizations
### Minor Issues (Non-Critical)
- [ ] Remove unused imports (linting warnings)
- [ ] Optimize bundle size with code splitting
- [ ] Add React error boundaries for better error handling
- [ ] Improve TypeScript strict mode compliance
### Performance Optimizations
- [ ] Add React.memo for expensive components
- [ ] Implement lazy loading for chart components
- [ ] Add data pagination for large datasets
- [ ] Optimize API response caching
## Testing Enhancements
### Recommended Testing
- [ ] Component unit tests for React components
- [ ] Integration testing for end-to-end billing flow
- [ ] Visual regression testing for UI consistency
- [ ] Performance testing for real-time updates
- [ ] Load testing for high-traffic scenarios
## Documentation Updates
### Planned Documentation
- [ ] Video tutorials for billing dashboard
- [ ] Interactive API documentation
- [ ] Best practices guide for cost optimization
- [ ] Troubleshooting guide with common issues
- [ ] Migration guide for existing users
## Timeline Estimates
### Phase 4 (Advanced Features)
- **Estimated Duration**: 4-6 weeks
- **Priority**: Medium
- **Dependencies**: Phase 1-3 completion ✅
### Phase 5 (Enterprise Features)
- **Estimated Duration**: 8-12 weeks
- **Priority**: Low
- **Dependencies**: Phase 4 completion, enterprise customer demand
## Success Metrics
### Phase 4 Success Criteria
- [ ] WebSocket integration reduces polling overhead by 80%
- [ ] Cost optimization suggestions reduce user costs by 15%
- [ ] Export functionality used by 30% of users
- [ ] Mobile app optimization increases mobile usage by 50%
### Phase 5 Success Criteria
- [ ] Multi-tenant support enables 10+ enterprise customers
- [ ] Advanced reporting reduces support tickets by 40%
- [ ] Integration enhancements increase customer retention by 25%
## Contributing
We welcome contributions to the subscription system roadmap. Please:
1. Review existing issues and feature requests
2. Discuss major features before implementation
3. Follow the established code standards
4. Add comprehensive tests for new features
5. Update documentation with changes
## Next Steps
- [Implementation Status](implementation-status.md) - Current features and metrics
- [Frontend Integration](frontend-integration.md) - Technical specifications
- [API Reference](api-reference.md) - Endpoint documentation
---
**Last Updated**: January 2025
**Current Phase**: Phase 3 Complete, Phase 4 Planning

241
docs-site/docs/features/subscription/setup.md Normal file
View File

@@ -0,0 +1,241 @@
# Subscription System Setup
Complete guide for installing and configuring the ALwrity usage-based subscription system.
## Prerequisites
- Python 3.8+
- PostgreSQL database (or SQLite for development)
- FastAPI backend environment
- Required Python packages: `sqlalchemy`, `loguru`, `fastapi`
## Installation
### 1. Database Migration
Run the database setup script to create all subscription tables:
```bash
cd backend
python scripts/create_subscription_tables.py
```
This script will:
- Create all subscription-related database tables
- Initialize default subscription plans (Free, Basic, Pro, Enterprise)
- Configure API pricing for all providers
- Verify the setup
### 2. Verify Installation
Test the subscription system:
```bash
python test_subscription_system.py
```
This will verify:
- Database table creation
- Pricing calculations
- Usage tracking
- Limit enforcement
- Error handling
- API endpoints
### 3. Start the Server
```bash
python start_alwrity_backend.py
```
## Configuration
### Environment Variables
Create or update your `.env` file with the following:
```env
# Database Configuration
DATABASE_URL=postgresql://user:password@localhost/alwrity
# For development, you can use SQLite:
# DATABASE_URL=sqlite:///./alwrity.db
# API Keys (required for usage tracking)
GEMINI_API_KEY=your_gemini_key
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
# ... other API keys as needed
# HuggingFace Pricing (optional, for GPT-OSS-120B via Groq)
HUGGINGFACE_INPUT_TOKEN_COST=0.000001
HUGGINGFACE_OUTPUT_TOKEN_COST=0.000003
```
### HuggingFace Pricing Configuration
HuggingFace API calls (specifically for GPT-OSS-120B model via Groq) are tracked and billed using configurable pricing.
#### Environment Variables
- `HUGGINGFACE_INPUT_TOKEN_COST`: Cost per input token (default: `0.000001` = $1 per 1M tokens)
- `HUGGINGFACE_OUTPUT_TOKEN_COST`: Cost per output token (default: `0.000003` = $3 per 1M tokens)
#### Updating Pricing
The pricing is automatically initialized when the database is set up. To update pricing after changing environment variables:
1. **Option 1**: Restart the backend server (pricing will be updated on next initialization)
2. **Option 2**: Run the database setup script again:
```bash
python backend/scripts/create_subscription_tables.py
```
#### Verify Pricing
Check that pricing is correctly configured by:
1. Checking the database `api_provider_pricing` table
2. Making a test API call and checking the cost in usage logs
3. Viewing the billing dashboard to see cost calculations
## Production Setup
### 1. Database
Use PostgreSQL for production:
```env
DATABASE_URL=postgresql://user:password@host:5432/alwrity_prod
```
### 2. Caching
Set up Redis for caching (optional but recommended):
```env
REDIS_URL=redis://localhost:6379/0
```
### 3. Email Notifications
Configure email service for usage alerts:
```env
SMTP_HOST=smtp.example.com
SMTP_PORT=587
SMTP_USER=alerts@alwrity.com
SMTP_PASSWORD=your_password
```
### 4. Monitoring and Alerting
Set up monitoring and alerting systems:
- Configure log aggregation
- Set up performance monitoring
- Configure alert thresholds
### 5. Payment Processing
Implement payment processing integration:
- Stripe integration
- Payment gateway setup
- Billing cycle management
## Middleware Integration
The subscription system automatically tracks API usage through enhanced middleware. The middleware:
- Detects API provider from request patterns
- Estimates token usage from request/response content
- Validates usage limits before processing
- Calculates costs in real-time
- Logs all API calls for tracking
No additional configuration is required - the middleware is automatically active once the subscription system is installed.
## Usage Limit Enforcement
The system enforces usage limits automatically:
```python
# Usage limits are checked before processing requests
can_proceed, message, usage_info = await usage_service.enforce_usage_limits(
user_id=user_id,
provider=APIProvider.GEMINI,
tokens_requested=1000
)
if not can_proceed:
return JSONResponse(
status_code=429,
content={"error": "Usage limit exceeded", "message": message}
)
```
## Testing
### Run Tests
```bash
python test_subscription_system.py
```
### Test Coverage
The test suite covers:
- Database table creation
- Pricing calculations
- Usage tracking
- Limit enforcement
- Error handling
- API endpoints
## Troubleshooting
### Common Issues
1. **Database Connection Errors**
- Check `DATABASE_URL` configuration
- Verify database is running
- Check network connectivity
2. **Missing API Keys**
- Verify all required keys are set in `.env`
- Check environment variable names match exactly
3. **Usage Not Tracking**
- Verify middleware is integrated
- Check database connection
- Review logs for errors
4. **Pricing Errors**
- Verify provider pricing configuration in database
- Check `api_provider_pricing` table
- Review pricing initialization logs
### Debug Mode
Enable debug logging:
```python
import logging
logging.basicConfig(level=logging.DEBUG)
```
### Support
For issues and questions:
1. Check the logs in `logs/subscription_errors.log`
2. Run the test suite to identify problems
3. Review the error handling documentation
4. Contact the development team
## Next Steps
- [API Reference](api-reference.md) - Endpoint documentation and examples
- [Pricing](pricing.md) - Subscription plans and API pricing details
- [Frontend Integration](frontend-integration.md) - Technical specifications for frontend
---
**Last Updated**: January 2025