# Subscription, Billing & Usage Tracking

This document details how ALwrity manages subscriptions, processes payments via Stripe, and tracks granular usage for every user interaction.

## 1. Subscription Model

ALwrity uses a **tier-based subscription model** enforced at the API gateway level.

### Tiers
- **Free**: Limited access, community support.
- **Basic**: Entry-level AI usage, standard support.
- **Pro**: High limits, advanced models (Gemini Pro, FLUX), priority support.
- **Enterprise**: Custom limits, dedicated infrastructure.

### Data Model (`UserSubscription`)
Stored in the user's SQLite database (`alwrity_user_{id}.db`):
- `stripe_customer_id`: Link to Stripe Customer.
- `stripe_subscription_id`: Active subscription ID.
- `plan_id`: Internal plan reference (linked to `SubscriptionPlan`).
- `status`: `active`, `past_due`, `canceled`, etc.
- `current_period_start` / `end`: Defines the billing cycle window.

## 2. Billing Integration (Stripe)

We use **Stripe** for all payments, webhooks, and portal management.

### Key Components
- **StripeService**: Handles checkout creation, portal sessions, and webhooks.
- **Webhooks**: Listens for events like `invoice.payment_succeeded`, `customer.subscription.updated`.
  - **Idempotency**: All webhooks are tracked in `ProcessedStripeEvent` to prevent duplicate processing.
  - **Reliability**: Events are processed transactionally; failures are logged and retried by Stripe.
- **Configuration**: Plan-to-Price mapping is loaded from environment variables (`STRIPE_PLAN_PRICE_MAPPING_TEST` / `_LIVE`) to ensure sync between code and Stripe Dashboard.

### Checkout Flow
1. Frontend calls `/api/subscription/create-checkout-session`.
2. Backend validates user and creates Stripe Session.
3. User pays on Stripe.
4. Stripe sends `checkout.session.completed` webhook.
5. Backend provisions subscription and credits in `UserSubscription`.

## 3. Usage Tracking

Every API call to an LLM provider is tracked, costed, and logged.

### Tracking Flow
1. **Pre-flight Check** (`check_usage_limits`):
   - Before generating content, the system estimates cost/tokens.
   - If user exceeds plan limits (e.g., "50 videos/month"), the request is rejected (429).
2. **Execution**: The provider generates the content.
3. **Post-execution Log** (`track_usage`):
   - Actual tokens/duration are measured.
   - Cost is calculated based on `APIProviderPricing` table.
   - Entry added to `APIUsageLog` (granular) and aggregated into `UsageSummary` (monthly totals).

### Database Tables
- **`APIUsageLog`**: Immutable ledger of every call.
  - Fields: `user_id`, `provider`, `model`, `input_tokens`, `output_tokens`, `cost`, `status_code`.
- **`UsageSummary`**: Aggregated stats per billing period.
  - Fields: `total_calls`, `total_cost`, `gemini_calls`, `video_calls`, etc.
  - **Unique Constraint**: Enforced on `(user_id, billing_period)` to prevent data drift.

### Pricing Engine (`PricingService`)
- Costs are not hardcoded. They are fetched from `APIProviderPricing` table.
- Supports per-token (text), per-image (media), and per-second (video/audio) pricing models.
- Admin can update pricing in DB without redeploying code.

## 4. Frontend Integration

- **Usage Dashboard**: Visualizes consumption vs. limits.
- **Real-time**: Usage stats are typically updated immediately after generation.
- **Limit Rings**: UI components show percentage used (e.g., "80% of monthly video limit").