Skip to content

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

Version: 1.0.0
Last Updated: January 2025