# DigiSim Subscription System

> Comprehensive subscription management system with tiered component access, PayPal integration, and dynamic UI updates based on user subscription status.

## Subscription Tiers

### FREE Tier
Basic digital logic components for educational introduction:
- **Logic Gates**: AND, OR, NOT, XOR, NAND, NOR, XNOR, Buffer
- **Input Components**: Switch, Constant values
- **Output Components**: Light indicators
- **Text Labels**: Circuit documentation and labeling
- **Circuit Quota**: Maximum of 5 saved circuits

### BASIC Tier ($7.00/month or $60.00/year)
For advanced students and serious hobbyists:
- **Full Component Library** (excluding CPU components)
- **Unlimited Saved Circuits**
- **Access to 66+ Pro Template Circuits**
- **Basic Oscilloscope & Analysis Tools**
- **Circuit Export and Sharing**
- **Access to Templates**

### PROFESSIONAL Tier ($19.00/month or $180.00/year)
For engineers, educators, and institutions:
- **All Basic tier features**
- **Full CPU Component Library**
- **Advanced 8-Channel Oscilloscope**
- **Priority Support**
- **Assembly Program Loader**
- **Pixel Screen 16x16**

## Available Components by Tier

### FREE Tier Components
- INPUT_SWITCH
- OUTPUT_LIGHT
- CONSTANT
- CONSTANT_ZERO
- AND
- OR
- NOT
- NAND
- NOR
- XOR
- XNOR
- BUFFER

### BASIC Tier Components
(All FREE tier components plus the following)
- CLOCK
- TRI_STATE_BUFFER
- MULTIPLEXER
- MULTIPLEXER_4TO1
- MULTIPLEXER_8TO1
- DEMULTIPLEXER
- DEMULTIPLEXER_1TO4
- DEMULTIPLEXER_1TO8
- DECODER
- DECODER_3TO8
- ENCODER
- ENCODER_8TO3
- HALF_ADDER
- FULL_ADDER
- ADDER
- ADDER_8BIT
- COMPARATOR
- COMPARATOR_8BIT
- ALU
- ALU_8BIT
- SR_LATCH
- D_LATCH
- D_FLIP_FLOP
- JK_FLIP_FLOP
- T_FLIP_FLOP
- REGISTER
- SHIFT_REGISTER
- COUNTER
- REGISTER_8BIT
- SHIFT_REGISTER_8BIT
- COUNTER_8BIT
- RAM
- ROM
- DIGIT_DISPLAY
- OSCILLOSCOPE
- TEXT
- FLAGS_REGISTER
- SEVEN_SEGMENT_DISPLAY

### PROFESSIONAL Tier Components
(All BASIC tier components plus the following)
- TRI_STATE_BUFFER_8BIT
- PROGRAM_COUNTER_8BIT
- INSTRUCTION_REGISTER
- CONTROL_UNIT
- OSCILLOSCOPE_8CH
- PIXEL_SCREEN_16x16
- ASSEMBLY_PROGRAM_LOADER

## Access Control Architecture

### Dynamic UI Updates
- **Visual Indicators**: Disabled components show reduced opacity and lock icons
- **Interactive Feedback**: Click-to-upgrade prompts for restricted components
- **Real-time Availability**: Components enable/disable with subscription changes
- **Professional Styling**: Material Design 3 compliant disabled states

### Component Availability Methods
```typescript
isComponentAvailable(componentType): boolean
getComponentClasses(componentType): string
isComponentDraggable(componentType): boolean
onComponentInteraction(event, componentType, action): void
onRestrictedComponentClick(componentType): void
```

## Backend Integration

### Authentication Response
Subscription data included in all auth responses:
```typescript
interface AuthResponse {
  accessToken: string;
  refreshToken: string;
  userSubscription: UserSubscriptionInfo;
  availableActions: AvailableActionsInfo;
}
```

### Subscription Data Structure
```typescript
interface UserSubscriptionInfo {
  planType: SubscriptionPlanType;
  planName: string;
  isActive: boolean;
  featureAccess: FeatureAccess;
  circuitQuota: CircuitQuota;
  status: string;
  expiresAt: Timestamp;
  billingCycle: string;
}
```

## PayPal Integration

### Subscription Creation
- **Plan Selection**: Monthly plans at $7.00 (Basic) and $19.00 (Professional)
- **Annual Billing**: Yearly plans at $60.00 (Basic) and $180.00 (Professional)
- **PayPal Checkout**: Secure payment processing
- **Subscription Activation**: Immediate feature access
- **Confirmation Flow**: Email and in-app notifications

### Subscription Management
- **Billing Cycle Changes**: Switch between monthly/yearly
- **Cancellation Options**: Immediate or end-of-cycle
- **Reactivation**: Resume cancelled subscriptions
- **Payment Updates**: Update payment methods

## State Management

### SubscriptionStateService
Centralized subscription state:
- **Session Persistence**: Maintain state across browser sessions
- **Reactive Updates**: Observable streams for state changes
- **Getter Methods**: Type-safe access to subscription properties
- **Error Handling**: Graceful fallbacks for invalid states

### Component Integration
- **Service Injection**: Subscription services in all relevant components
- **Reactive Subscriptions**: Automatic UI updates on state changes
- **Memory Management**: Proper subscription cleanup on component destroy
- **Performance Optimization**: Efficient change detection strategies

## User Experience Features

### Upgrade Prompts
- **Contextual Messaging**: Specific benefits for each component tier
- **Professional Design**: Material Design 3 snackbar styling
- **Clear Call-to-Action**: Direct links to subscription management
- **Feature Highlighting**: Emphasize premium capabilities

### Visual Feedback
- **Component Styling**: 
  - 38% opacity for disabled components (Material Design standard)
  - Diagonal stripe overlay pattern
  - Lock icon indicators
  - Not-allowed cursor states
- **Hover Effects**: Disabled for restricted components
- **Color Coding**: Consistent visual language for access levels

### Subscription Badges
- **Header Display**: Current plan shown in navigation
- **Badge Extraction**: Intelligent plan name parsing
- **Fallback Logic**: Multiple data sources for reliability
- **Responsive Design**: Appropriate sizing for different screen sizes

## Analytics and Monitoring

### Usage Tracking
- **Component Interactions**: Track attempts to use restricted components
- **Upgrade Conversions**: Monitor upgrade prompt effectiveness
- **Feature Usage**: Analyze which premium features drive subscriptions
- **User Journey**: Track progression through subscription tiers

### Performance Metrics
- **Permission Check Performance**: Monitor service response times
- **UI Update Efficiency**: Track reactive update performance
- **Memory Usage**: Monitor subscription service memory consumption
- **Error Rates**: Track subscription-related errors and failures

## Security and Compliance

### Data Protection
- **Subscription Data Encryption**: Secure storage of sensitive information
- **PCI Compliance**: PayPal integration meets security standards
- **GDPR Compliance**: Proper handling of European user data
- **Session Security**: Secure subscription state management

### Access Validation
- **Server-side Verification**: Backend validates all subscription claims
- **Token-based Security**: JWT tokens include subscription information
- **Rate Limiting**: Prevent abuse of subscription endpoints
- **Audit Logging**: Track subscription changes and access attempts