# Subscriptions & Plans Module

## Purpose
The subscription system is the **monetization and feature access control** layer. Plans define feature limits, and subscriptions track each subscriber's active plan, status, and usage.

## Architecture Overview

Three independent but parallel subscription tracks:

```
ProgramPlan ─── ProgramSubscription ─── Program (Tenant)
TeacherPlan ─── TeacherSubscription ─── User (Teacher)
StudentPlan ─── StudentSubscription ─── User (Student)
```

Each track uses:
- `laravelcm/laravel-subscriptions` package for core subscription/plan/feature models
- Custom `*Subscription` models with plan snapshots, status tracking, and grace periods
- `SubscriptionUsageObserver` for automatic feature usage tracking

## Plan Models

### ProgramPlan (`app/Models/ProgramPlan.php`)
- **Fields:** `name` (json), `picture`, `price`, `duration_days`, `is_active`, `description` (json), `is_default`, `is_initial`
- Resource limit columns: `no_of_teachers`, `no_of_marathons`, `no_of_competition_per_marathon`, `no_of_announcements`, etc.

### TeacherPlan (`app/Models/TeacherPlan.php`)
- **Fields:** `name` (json), `picture`, `price`, `duration_days`, `is_active`, `description` (json), `is_default`, `is_initial`
- Resource limit columns: `max_courses`, `max_students`, `available_storage_videos`, `no_of_groups`, `no_of_students_per_group`, `no_of_competitions`, `no_of_exams`, etc.

### StudentPlan (`app/Models/StudentPlan.php`)
- **Fields:** `name` (json), `picture`, `price`, `duration_days`, `is_active`, `description` (json), `is_default`, `is_initial`
- Resource limit columns: `no_of_available_self_training`, `no_of_attempts_per_self_training`, etc.

## Subscription Models

### ProgramSubscription (`app/Models/ProgramSubscription.php`)
- **Fields:** `program_id`, `program_plan_id`, `starts_at`, `ends_at`, `is_active`, `status`, `plan_snapshot` (json), `grace_period_ends_at`
- Uses traits: `HasPlanSnapshot`, `HasSubscriptionStatus`, `HasSubscriptionHistory`
- Relationships: `program()`, `plan()`, `usage()`

### TeacherSubscription (`app/Models/TeacherSubscription.php`)
- **Fields:** `user_id`, `teacher_plan_id`, `starts_at`, `ends_at`, `is_active`, `status`, `plan_snapshot` (json), `grace_period_ends_at`
- Same traits as ProgramSubscription
- Relationships: `user()`, `plan()`, `usage()`

### StudentSubscription (`app/Models/StudentSubscription.php`)
- **Fields:** `user_id`, `student_plan_id`, `starts_at`, `ends_at`, `is_active`, `status`, `plan_snapshot` (json), `grace_period_ends_at`
- Same traits as above
- Relationships: `user()`, `plan()`, `usage()`

### Shared Concerns (Traits)
- `HasPlanSnapshot` — Snapshots plan features at subscription time for consistent billing
- `HasSubscriptionStatus` — Status management (active, expired, suspended, cancelled, pending)
- `HasSubscriptionHistory` — Tracks subscription lifecycle changes via `SubscriptionHistoryService`

### Usage Models
- `ProgramSubscriptionUsage`, `TeacherSubscriptionUsage`, `StudentSubscriptionUsage` — Track per-feature consumption
- Linked to `SubscriptionUsage` from the laravel-subscriptions package

## Subscription Statuses (`app/Enums/SubscriptionStatus.php`)
States a subscription can be in: `active`, `expired`, `suspended`, `cancelled`, `pending`, `grace_period`

## Core Services

### SubscriptionService (`app/Services/SubscriptionService.php`)
- Central facade for subscription operations
- Singleton registered in `AppServiceProvider`
- Methods: `subscribeProgramToPlan()`, `subscribeTeacherToPlan()`, `subscribeStudentToPlan()`
- Handles plan changes, renewals, cancellations, and suspension

### SubscriptionRequestService (`app/Services/SubscriptionRequestService.php`)
- Manages subscription upgrade/downgrade requests
- Handles approval workflow before plan changes take effect

### Key Workflow Services
- `RenewalWorkflow` — Handles subscription renewal logic
- `PlanChangeWorkflow` — Handles plan upgrade/downgrade with proration
- `NotificationHandler` — Sends subscription-related notifications via NotificationEngine

## Feature Entitlement Integration
The feature entitlement engine (`FeatureGate`) reads plan feature limits from:
1. Active subscription's `plan_snapshot` (for historical consistency)
2. Active subscription's plan model (for current plan definition)
3. `config/features.php` (for default limits)

## Observers
- `GenericSubscriptionObserver` — Handles events for ALL subscription models (Program, Teacher, Student)
- `SubscriptionUsageObserver` — Tracks resource creation/deletion for usage metering
- Legacy observers (`ProgramSubscriptionObserver`, `TeacherSubscriptionObserver`, `StudentSubscriptionObserver`) kept as deprecated delegates

## Scheduled Tasks
- `notifications:plan-expiring` — Daily 6:00 AM, checks subscriptions expiring in 7 days and 1 day
- `notifications:plan-expired` — Daily 12:30 AM, deactivates expired subscriptions (respecting grace period)
- `subscriptions:process-grace-period` — Daily 2:00 AM, processes grace period expiration
- `subscriptions:auto-suspend` — Daily 12:00 AM, suspends subscriptions past grace period, expires long-suspended (30+ days)
- `notifications:trial-ending` — Daily 7:00 AM, trial ending reminders
- `notifications:feature-limit` — Daily 12:00 PM, feature usage limit warnings

## Filament Pages
- `Subscriptions` (`app/Filament/Pages/Subscriptions.php`) — Subscription management for admins
- `Plans` (`app/Filament/Pages/Plans.php`) — Plan management for admins
- `MySubscription` (`app/Filament/Pages/MySubscription.php`) — User-facing subscription view in Program panel

## Filament Widgets
- `SubscriptionStatusWidget` — Current subscription status overview
- `ExpiringSubscriptionsWidget` — Subscriptions nearing expiration
- `SubscriptionUsageWidget` — Feature usage visualization
- `PaymentQueueWidget` — Pending payment queue

## Related Workflows
- **[Subscription Lifecycle Workflow](../WORKFLOWS.md#7-subscription-lifecycle-workflow)** — End-to-end subscription creation, activation, grace period, and expiration
- **[Feature Usage Tracking Workflow](../WORKFLOWS.md#8-feature-usage-tracking-workflow)** — Automatic consumption and release of feature usage counters