ALwrity/backend/services/subscription

Subscription Services Package

Overview

This package consolidates all subscription, billing, and usage tracking related services and middleware into a single, well-organized module. This follows the same architectural pattern as the onboarding package for consistency and maintainability.

Package 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 with usage tracking
└── README.md                           # This documentation

Services

PricingService

• File: pricing_service.py
• Purpose: Manages API pricing, cost calculation, and subscription limits
• Key Features:
  • Dynamic pricing based on API provider and model
  • Cost calculation for input/output tokens
  • Subscription limit enforcement
  • Billing period management

UsageTrackingService

• File: usage_tracking_service.py
• Purpose: Comprehensive tracking of API usage, costs, and subscription limits
• Key Features:
  • Real-time usage tracking
  • Cost calculation and billing
  • Usage limit enforcement with TTL caching
  • Usage alerts and notifications

SubscriptionExceptionHandler

• File: exception_handler.py
• Purpose: Centralized exception handling for subscription-related errors
• Key Features:
  • Custom exception types
  • Error handling decorators
  • Consistent error responses

Monitoring Middleware

• File: monitoring_middleware.py
• Purpose: FastAPI middleware for API monitoring and usage tracking
• Key Features:
  • Request/response monitoring
  • Usage tracking integration
  • Performance metrics
  • Database API monitoring

Usage

Import Pattern

Always use the consolidated package for subscription-related imports:

# ✅ Correct - Use consolidated package
from services.subscription import PricingService, UsageTrackingService
from services.subscription import SubscriptionExceptionHandler
from services.subscription import check_usage_limits_middleware

# ❌ Incorrect - Old scattered imports
from services.pricing_service import PricingService
from services.usage_tracking_service import UsageTrackingService
from middleware.monitoring_middleware import check_usage_limits_middleware

Service Initialization

from services.subscription import PricingService, UsageTrackingService
from services.database import get_db

# Get database session
db = next(get_db())

# Initialize services
pricing_service = PricingService(db)
usage_service = UsageTrackingService(db)

Middleware Registration

from services.subscription import monitoring_middleware

# Register middleware in FastAPI app
app.middleware("http")(monitoring_middleware)

Database Models

The subscription services use the following database models (defined in backend/models/subscription_models.py):

• APIProvider - API provider enumeration
• SubscriptionPlan - Subscription plan definitions
• UserSubscription - User subscription records
• UsageSummary - Usage summary by billing period
• APIUsageLog - Individual API usage logs
• APIProviderPricing - Pricing configuration
• UsageAlert - Usage limit alerts
• SubscriptionTier - Subscription tier definitions
• BillingCycle - Billing cycle enumeration
• UsageStatus - Usage status enumeration

Key Features

1. Database-Only Persistence

• All data stored in database tables
• No file-based storage
• User-isolated data access

2. TTL Caching

• In-memory caching for performance
• 30-second TTL for usage limit checks
• 10-minute TTL for dashboard data

3. Real-time Monitoring

• Live API usage tracking
• Performance metrics collection
• Error rate monitoring

4. Flexible Pricing

• Per-provider pricing configuration
• Model-specific pricing
• Dynamic cost calculation

Error Handling

The package provides comprehensive error handling:

from services.subscription import (
    SubscriptionException,
    UsageLimitExceededException,
    PricingException,
    TrackingException
)

try:
    # Subscription operation
    pass
except UsageLimitExceededException as e:
    # Handle usage limit exceeded
    pass
except PricingException as e:
    # Handle pricing error
    pass

Configuration

The services use environment variables for configuration:

• SUBSCRIPTION_DASHBOARD_NOCACHE - Bypass dashboard cache
• ENABLE_ALPHA - Enable alpha features (default: false)

Migration from Old Structure

This package consolidates the following previously scattered files:

• backend/services/pricing_service.py → subscription/pricing_service.py
• backend/services/usage_tracking_service.py → subscription/usage_tracking_service.py
• backend/services/subscription_exception_handler.py → subscription/exception_handler.py
• backend/middleware/monitoring_middleware.py → subscription/monitoring_middleware.py

Benefits

1. Single Package: All subscription logic in one location
2. Clear Ownership: Easy to find subscription-related code
3. Better Organization: Follows same pattern as onboarding
4. Easier Maintenance: Single source of truth for billing logic
5. Consistent Architecture: Matches onboarding consolidation

Related Packages

• services.onboarding - Onboarding and user setup
• models.subscription_models - Database models
• api.subscription - API endpoints (modular structure with routes in api/subscription/routes/)