# Feature Toggle Types Guide

This guide explains the different types of feature toggles available in the Flux Gate system and when to use each type.

## 🎯 Overview

The Flux Gate supports two main types of feature toggles: **Simple Features** and **Contextual Features**. Each type serves different use cases and provides different levels of control over feature rollout.

## 🔗 Feature Type Comparison

| Aspect | Simple Features | Contextual Features |
|--------|-----------------|-------------------|
| **Complexity** | Basic on/off toggle | Advanced targeting system |
| **Targeting** | Binary enable/disable | Context-based user targeting |
| **Rollout Control** | All or nothing | Percentage-based gradual rollout |
| **Configuration** | Minimal setup | Detailed criteria configuration |
| **Use Cases** | Basic feature gating | A/B testing, gradual rollouts |
| **Pipeline Support** | Full pipeline support | Full pipeline support |
| **Team Scope** | Team-based | Team-based with context access |

## 🔘 Simple Features

### Overview

Simple Features are basic on/off toggles that provide binary feature control without user targeting capabilities.

### Characteristics

- **Binary State**: Features are either fully enabled or disabled
- **No Targeting**: All users see the same feature state
- **Simple Configuration**: Minimal setup required
- **Fast Evaluation**: Quick feature state evaluation
- **Clear Semantics**: Easy to understand and manage

### When to Use Simple Features

#### Ideal Use Cases

1. **Kill Switches**: Emergency feature disabling
2. **Maintenance Modes**: Temporary feature disabling for maintenance
3. **Feature Releases**: Complete feature enable/disable
4. **System Toggles**: Infrastructure or system-level feature control
5. **Binary Decisions**: Features that don't require user targeting

#### Example Scenarios

```
✅ Good for Simple Features:
- Maintenance mode toggle
- New API endpoint enable/disable
- Debug logging on/off
- Feature complete replacement
- Emergency kill switch

❌ Not suitable for Simple Features:
- Gradual user rollout
- A/B testing
- User segment targeting
- Percentage-based rollout
- Context-dependent features
```

### Simple Feature Configuration

#### Basic Settings

| Setting | Description |
|---------|-------------|
| **Feature Key** | Unique identifier for the feature |
| **Description** | Purpose and details of the feature |
| **Enabled Status** | Current on/off state |
| **Pipeline Stages** | Deployment stages across environments |

#### Pipeline Configuration

Simple features use standard pipeline workflows:

```
Development → Staging → Production
     ↓           ↓          ↓
  Feature     Feature    Feature
 Disabled    Enabled    Enabled
```

Each stage can have different enabled/disabled states.

### Simple Feature Deployment

#### Deployment Process

1. **Create Feature**: Set up simple feature with pipeline
2. **Stage Configuration**: Configure enable/disable per stage
3. **Request Deployment**: Request stage deployment through approval workflow
4. **Approval**: Approvers review and approve deployment
5. **Activation**: Feature becomes active in target environment

#### Example Deployment Flow

```
Stage 1 (Development): Enabled for testing
Stage 2 (Staging): Enabled for QA validation  
Stage 3 (Production): Disabled until ready
Stage 4 (Production): Enabled for all users
```

## 🎯 Contextual Features

### Overview

Contextual Features provide sophisticated user targeting based on user attributes, device characteristics, and custom criteria.

### Characteristics

- **Context-Based Targeting**: Target users based on attributes
- **Percentage Rollout**: Gradual rollout with percentage control
- **Multiple Criteria**: Combine different targeting criteria
- **Complex Configuration**: Detailed setup with context definitions
- **Flexible Evaluation**: Dynamic feature evaluation based on user context

### When to Use Contextual Features

#### Ideal Use Cases

1. **Gradual Rollouts**: Slowly roll out features to increasing user percentages
2. **A/B Testing**: Test different feature variants with different user groups
3. **User Segmentation**: Target specific user segments or demographics
4. **Device Targeting**: Target based on device type, OS, or browser
5. **Geographic Rollouts**: Deploy features by geographic region
6. **Beta Programs**: Limit features to beta users or specific user groups

#### Example Scenarios

```
✅ Perfect for Contextual Features:
- Roll out to 25% of premium users
- A/B testing new checkout flow
- Mobile-only feature rollout
- Geographic rollout (US first, then Europe)
- Beta user exclusive access

✅ Also good for:
- Canary deployments
- User tier-based features
- Performance-sensitive rollouts
- Risk-managed deployments
```

### Context-Based Targeting

#### Available Context Types

| Context Type | Examples | Use Cases |
|--------------|----------|-----------|
| **User Attributes** | user_id, email_domain, subscription_tier | User-specific targeting |
| **Device Properties** | device_type, operating_system, browser | Device-based features |
| **Geographic Data** | country, region, timezone | Location-based rollouts |
| **Custom Criteria** | customer_segment, experiment_group | Business-specific targeting |

#### Context Configuration

For each pipeline stage, you can configure multiple targeting criteria:

| Field | Description | Example |
|-------|-------------|---------|
| **Context** | The targeting context | "device_type" |
| **Context Key** | Specific value to match | "mobile" |
| **Rollout Percentage** | Percentage of matching users | 50% |

### Contextual Feature Configuration

#### Stage Criteria Setup

Each pipeline stage can have multiple targeting criteria:

```
Stage 1: Beta Testing
- Context: user_role
- Key: beta_tester  
- Rollout: 100% (all beta testers)

Stage 2: Premium Rollout
- Context: subscription_tier
- Key: premium
- Rollout: 25% (25% of premium users)

Stage 3: Mobile Users
- Context: device_type
- Key: mobile
- Rollout: 50% (50% of mobile users)

Stage 4: General Availability
- Context: user_id
- Key: all_users
- Rollout: 100% (everyone)
```

#### Multiple Criteria per Stage

You can configure multiple targeting criteria for a single stage:

```
Stage: Regional Premium Rollout
Criteria 1:
- Context: geographic_region
- Key: north_america
- Rollout: 75%

Criteria 2:
- Context: subscription_tier
- Key: premium
- Rollout: 50%

Result: Users matching BOTH criteria get feature
```

## 📊 Feature Type Selection Guide

### Decision Matrix

Use this matrix to choose the appropriate feature type:

| Question | Simple | Contextual |
|----------|--------|------------|
| Do you need user targeting? | No | Yes |
| Do you need gradual rollout? | No | Yes |
| Is this for A/B testing? | No | Yes |
| Do you need percentage control? | No | Yes |
| Is this a kill switch? | Yes | No |
| Do you need context evaluation? | No | Yes |
| Is quick deployment important? | Yes | Depends |

### Selection Flowchart

```
Start: Need feature toggle?
    ↓
Do you need user targeting or gradual rollout?
    ↓                    ↓
   No                   Yes
    ↓                    ↓
Simple Feature    Contextual Feature
    ↓                    ↓
Binary on/off    Context-based targeting
```

## 🔄 Feature Type Migration

### Simple to Contextual Migration

You can migrate simple features to contextual features:

#### Migration Process

1. **Edit Feature**: Access feature editing interface
2. **Change Type**: Update feature type to "CONTEXTUAL"
3. **Configure Contexts**: Set up context-based targeting criteria
4. **Update Stages**: Configure stage criteria for each pipeline stage
5. **Test Configuration**: Validate targeting works as expected
6. **Deploy Changes**: Update feature configuration

#### Migration Considerations

⚠️ **Important**: Changing feature types affects how features are evaluated in your application.

- **Application Integration**: Ensure your application can handle contextual evaluation
- **Context Data**: Verify context data is available in your application
- **Testing**: Thoroughly test feature evaluation with different contexts
- **Rollback Plan**: Have a plan to revert if issues occur

### Contextual to Simple Migration

You can also simplify contextual features to simple features:

#### Simplification Process

1. **Remove Criteria**: Delete all context-based targeting criteria
2. **Change Type**: Update feature type to "SIMPLE" 
3. **Configure Stages**: Set binary enable/disable for each stage
4. **Update Application**: Remove context evaluation logic
5. **Deploy Changes**: Update feature configuration

## 🚨 Feature Type Best Practices

### Simple Feature Best Practices

1. **Clear Purpose**: Use for clear binary decisions
2. **Emergency Readiness**: Ideal for kill switches
3. **Simple Naming**: Use descriptive names for simple features
4. **Documentation**: Document the binary behavior clearly

### Contextual Feature Best Practices

1. **Context Planning**: Plan context types before implementation
2. **Gradual Rollout**: Start with small percentages and increase gradually
3. **Monitoring**: Monitor feature performance during rollout
4. **Fallback Strategy**: Have fallback behavior when context unavailable

### General Best Practices

1. **Type Consistency**: Use consistent feature types within related features
2. **Documentation**: Document feature type rationale
3. **Team Training**: Ensure team understands both feature types
4. **Regular Review**: Periodically review feature type choices

## 🔧 Implementation Considerations

### Application Integration

#### Simple Feature Integration

```javascript
// Simple feature evaluation
const isNewUIEnabled = featureToggle.isEnabled('new-ui-feature');

if (isNewUIEnabled) {
  renderNewUI();
} else {
  renderOldUI();
}
```

#### Contextual Feature Integration

```javascript
// Contextual feature evaluation
const userContext = {
  user_id: getCurrentUserId(),
  device_type: getDeviceType(),
  subscription_tier: getUserTier()
};

const isNewUIEnabled = featureToggle.isEnabledForContext(
  'new-ui-feature', 
  userContext
);

if (isNewUIEnabled) {
  renderNewUI();
} else {
  renderOldUI();
}
```

### Performance Considerations

#### Simple Features
- ✅ Fast evaluation (simple boolean check)
- ✅ Low overhead
- ✅ Cacheable results
- ✅ Minimal network requests

#### Contextual Features  
- ⚠️ More complex evaluation
- ⚠️ Requires context data
- ⚠️ More network requests
- ✅ Flexible targeting

## 🔗 Related Documentation

- [Feature Toggle Management](Feature-Toggle-Management.md) - Creating and managing features
- [Context Management](Context-Management.md) - Setting up contexts for targeting
- [Pipeline Management](Pipeline-Management.md) - Configuring deployment pipelines
- [Stage Approval Workflow](Stage-Approval-Workflow.md) - Deployment approval process

---

*Need help? Check the [Troubleshooting](Troubleshooting.md) guide or create an issue in the project repository.*