Membership & Quota System

📋 Overview

The Membership & Quota System manages subscription plans with feature-based quota tracking and usage logging. This enables tiered access control based on membership levels.

Membership Plans - Define subscription tiers with pricing and duration
Feature Limits - Configure what each plan includes (API calls, posts, storage)
Quota Tracking - Real-time monitoring of current period usage
Usage Logging - Complete audit trail of all usage transactions

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                         MEMBERSHIP & QUOTA SYSTEM                             │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐     ┌──────────────────────┐                             │
│  │ memberships │────▶│membership_features  │                             │
│  │              │     │(Plan Definitions)    │                             │
│  └──────┬───────┘     └──────────────────────┘                             │
│         │                                                                   │
│         ▼                                                                    │
│  ┌──────────────────┐                                                       │
│  │user_memberships  │◀─── app_users.user_id                                │
│  │(Active Subs)     │                                                        │
│  └──────────────────┘                                                       │
│         │                                                                   │
│         ▼                                                                    │
│  ┌──────────────────────────┐                                              │
│  │user_membership_quotas     │  ← Updated frequently                        │
│  │(Current Period Usage)    │    (after each action)                       │
│  │                          │                                              │
│  │ - feature_key            │                                              │
│  │ - limit_value            │  NULL = unlimited                            │
│  │ - used_value             │  Current usage count                          │
│  │ - remaining_value        │  Auto-calculated                              │
│  │ - period_start/end       │  For periodic resets                           │
│  └────────┬─────────────────┘                                              │
│           │                                                                 │
│           ▼                                                                  │
│  ┌──────────────────┐                                                       │
│  │user_usage_logs   │  ← Append-only audit trail                           │
│  │(Transaction Hist)│    (Every usage event)                                │
│  │                  │                                                       │
│  │ - action_type    │  api_call, post_create, etc.                         │
│  │ - quantity       │  Number of units consumed                            │
│  │ - resource_id    │  Reference to created item                           │
│  │ - metadata       │  Context information                                 │
│  └──────────────────┘                                                       │
│                                                                              │
│  QUOTA CHECK FLOW:                                                           │
│  ┌─────────────────────────────────────────────────────────────────────┐     │
│  │ 1. User initiates action (e.g., Create Post)                        │     │
│  │ 2. Get user's active membership                                      │     │
│  │ 3. Get quota for feature_key='posts'                                 │     │
│  │ 4. Check: remaining_value > 0 OR remaining_value IS NULL            │     │
│  │ 5. If OK:                                                            │     │
│  │    - Log to user_usage_logs                                          │     │
│  │    - Update user_membership_quotas (used_value++, remaining--)       │     │
│  │    - Process request                                                │     │
│  │ 6. If exceeded: Return error with upgrade suggestion                │     │
│  └─────────────────────────────────────────────────────────────────────┘     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

📊 Table Reference

memberships

Defines available membership plans with pricing and duration.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`name`	VARCHAR(100)	NOT NULL	Plan name (Basic, Pro, Premium)
`slug`	VARCHAR(50)	UNIQUE	URL-friendly identifier (basic-plan)
`description`	TEXT	NULLABLE	Plan description
`duration_days`	INT	NULLABLE	Duration in days (NULL = lifetime)
`price`	DECIMAL(10,2)	Default: 0	Plan price
`currency`	CHAR(3)	Default: INR	ISO currency code
`level`	TINYINT	Default: 0	Plan hierarchy level
`is_active`	BOOLEAN	Default: true	Plan availability

membership_features

Defines what features each membership plan includes and their limits.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`membership_id`	BIGINT	FK	References memberships.id
`feature_key`	VARCHAR(50)	NOT NULL	Feature identifier (api_calls, posts, storage)
`feature_name`	VARCHAR(100)	NOT NULL	Display name (API Calls)
`limit_value`	INT	NULLABLE	NULL = unlimited
`period`	ENUM	Default: lifetime	lifetime, monthly, yearly, daily

user_memberships

User's active and historical subscriptions.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`user_id`	VARCHAR(32)	FK	References app_users.user_id
`membership_id`	BIGINT	FK	References memberships.id
`status`	ENUM	Default: active	active, expired, cancelled, pending
`start_date`	DATE	NOT NULL	Subscription start date
`end_date`	DATE	NULLABLE	Subscription end date (NULL = lifetime)
`auto_renew`	BOOLEAN	Default: false	Auto-renewal enabled

user_membership_quotas

Current period quota tracking. Updated after each usage.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`user_id`	VARCHAR(32)	FK	References app_users.user_id
`user_membership_id`	BIGINT	FK	References user_memberships.id
`feature_key`	VARCHAR(50)	NOT NULL	Feature identifier
`limit_value`	INT	NULLABLE	NULL = unlimited
`used_value`	INT	Default: 0	Current usage count
`remaining_value`	INT	NULLABLE	Auto-calculated (limit - used)
`period_start`	DATE	NOT NULL	Period start date
`period_end`	DATE	NOT NULL	Period end date

user_usage_logs

Append-only transaction history. Complete audit trail of all usage.

Field	Type	Attributes	Description
`id`	BIGINT	PK, Auto Increment	Primary key
`user_id`	VARCHAR(32)	FK	References app_users.user_id
`feature_key`	VARCHAR(50)	NOT NULL	Feature being used
`action_type`	VARCHAR(50)	NOT NULL	api_call, post_create, file_upload, etc.
`quantity`	INT	Default: 1	Units consumed
`resource_id`	VARCHAR(100)	NULLABLE	Reference to created resource
`metadata`	JSON	NULLABLE	Additional context
`created_at`	TIMESTAMP	Auto	Usage timestamp

💎 Default Membership Plans

Free

₹0 • Lifetime

• 100 API calls/month
• 10 posts/month
• 100MB storage

Basic

₹199/month • 30 days

• 1,000 API calls/month
• 50 posts/month
• 500MB storage

Pro

₹499/month • 30 days

• 10,000 API calls/month
• 500 posts/month
• 2GB storage

Premium

₹999/month • 30 days

• 50,000 API calls/month
• 2,000 posts/month
• 10GB storage

Enterprise

₹9,999/year • 365 days

• Unlimited API calls
• Unlimited posts
• Unlimited storage

💻 Usage Examples

// Check quota before allowing action
$quota = UserMembershipQuota::where('user_id', $userId)
    ->where('feature_key', 'posts')
    ->where('period_start', '<=', now())
    ->where('period_end', '>', now())
    ->first();

if ($quota && ($quota->remaining_value > 0 || $quota->remaining_value === null)) {
    // Allow action
} else {
    // Quota exceeded
    return response()->json([
        'error' => 'Quota exceeded',
        'message' => 'You have reached your monthly post limit.',
        'upgrade_suggestion' => 'Upgrade to Pro plan for 500 posts/month',
    ], 429);
}

// Log usage and update quota
DB::transaction(function() use ($userId, $featureKey) {
    // Log the usage
    UserUsageLog::create([
        'user_id' => $userId,
        'feature_key' => $featureKey,
        'action_type' => 'post_create',
        'quantity' => 1,
        'resource_id' => $postId,
        'metadata' => ['title' => $post->title],
    ]);

    // Update quota
    $quota = UserMembershipQuota::where('user_id', $userId)
        ->where('feature_key', $featureKey)
        ->first();

    $quota->increment('used_value');
    if ($quota->limit_value !== null) {
        $quota->update(['remaining_value' => $quota->limit_value - $quota->used_value]);
    }
});

// Get user's current membership with features
$membership = UserMembership::where('user_id', $userId)
    ->where('status', 'active')
    ->where(function($q) {
        $q->whereNull('end_date')
          ->orWhere('end_date', '>', now());
    })
    ->with('membership.features')
    ->first();