feature flags

apps/api/src/config/features.config.ts

@@ -2,33 +2,121 @@ import { FeatureFlagConfig } from './feature-types';
 
 /**
  * Feature flag configuration for all environments
- * This provides type safety, IntelliSense, and environment-specific settings
+ * 
+ * ARCHITECTURE: API-Driven Features
+ * - All feature control comes from the API /features endpoint
+ * - FeatureFlagService fetches and caches features
+ * - Components use FeatureFlagService or ModeGuard for conditional rendering
+ * 
+ * FEATURE STATES - DETAILED EXPLANATION:
+ * 
+ * 'enabled' = Feature is fully available to users
+ *   - Visible in UI
+ *   - Fully functional
+ *   - No restrictions
+ *   - Example: "Users can create leagues"
+ * 
+ * 'disabled' = Feature is turned off for everyone
+ *   - Not visible in UI (or shown as unavailable)
+ *   - Non-functional
+ *   - Users cannot access it
+ *   - Use when: Feature is broken, not ready, or intentionally removed
+ *   - Example: "Sponsor management disabled due to bug"
+ * 
+ * 'coming_soon' = Feature is visible but not yet available
+ *   - Visible in UI with "Coming Soon" badge
+ *   - Shows users what's coming
+ *   - Builds anticipation
+ *   - Use when: Feature is in development, users should know about it
+ *   - Example: "New UI coming soon" - users see it but can't use it
+ * 
+ * 'hidden' = Feature is completely invisible
+ *   - Not shown in UI at all
+ *   - No user knows it exists
+ *   - Use when: Feature is experimental, internal-only, or not ready for ANY visibility
+ *   - Example: "Experimental AI feature" - only devs know it exists
+ * 
+ * DECISION TREE:
+ * - Should users see this feature exists? 
+ *   - NO → 'hidden' or 'disabled'
+ *   - YES → Should they be able to use it?
+ *     - NO → 'coming_soon'
+ *     - YES → 'enabled'
+ * 
+ * REAL-WORLD EXAMPLES:
+ * - 'enabled': Dashboard, leagues, teams (core features working)
+ * - 'disabled': Sponsor management (broken, don't show anything)
+ * - 'coming_soon': New UI redesign (users see "coming soon" banner)
+ * - 'hidden': Experimental chat feature (internal testing only)
  */
 export const featureConfig: FeatureFlagConfig = {
-  // Development environment - features for local development
+  // Development environment - all features enabled for testing
   development: {
+    // Core platform features
+    platform: {
+      dashboard: 'enabled',
+      leagues: 'enabled',
+      teams: 'enabled',
+      drivers: 'enabled',
+      races: 'enabled',
+      leaderboards: 'enabled',
+    },
+    // Authentication & onboarding
+    auth: {
+      signup: 'enabled',
+      login: 'enabled',
+      forgotPassword: 'enabled',
+      resetPassword: 'enabled',
+    },
+    onboarding: {
+      wizard: 'enabled',
+    },
+    // Sponsor features
     sponsors: {
       portal: 'enabled',
       dashboard: 'enabled',
       management: 'enabled',
+      campaigns: 'enabled',
+      billing: 'enabled',
     },
+    // Admin features
     admin: {
       dashboard: 'enabled',
       userManagement: 'enabled',
       analytics: 'enabled',
     },
+    // Beta features for testing
     beta: {
-      newUI: 'enabled', // Enable new UI for testing
+      newUI: 'enabled',
       experimental: 'coming_soon',
     },
   },
 
-  // Test environment - features for automated tests
+  // Test environment - all features enabled for automated tests
   test: {
+    platform: {
+      dashboard: 'enabled',
+      leagues: 'enabled',
+      teams: 'enabled',
+      drivers: 'enabled',
+      races: 'enabled',
+      leaderboards: 'enabled',
+    },
+    auth: {
+      signup: 'enabled',
+      login: 'enabled',
+      forgotPassword: 'enabled',
+      resetPassword: 'enabled',
+    },
+    onboarding: {
+      wizard: 'enabled',
+    },
     sponsors: {
       portal: 'enabled',
       dashboard: 'enabled',
       management: 'enabled',
+      campaigns: 'enabled',
+      billing: 'enabled',
     },
     admin: {
       dashboard: 'enabled',
@@ -41,18 +129,42 @@ export const featureConfig: FeatureFlagConfig = {
     },
   },
 
-  // Staging environment - features for pre-production testing
+  // Staging environment - controlled feature rollout
   staging: {
+    // Core platform features
+    platform: {
+      dashboard: 'enabled',
+      leagues: 'enabled',
+      teams: 'enabled',
+      drivers: 'enabled',
+      races: 'enabled',
+      leaderboards: 'enabled',
+    },
+    // Authentication & onboarding
+    auth: {
+      signup: 'enabled',
+      login: 'enabled',
+      forgotPassword: 'enabled',
+      resetPassword: 'enabled',
+    },
+    onboarding: {
+      wizard: 'enabled',
+    },
+    // Sponsor features (gradual rollout)
     sponsors: {
       portal: 'enabled',
       dashboard: 'enabled',
-      management: 'enabled',
+      management: 'coming_soon', // Ready for testing but not fully rolled out
+      campaigns: 'enabled',
+      billing: 'enabled',
     },
+    // Admin features
     admin: {
       dashboard: 'enabled',
       userManagement: 'enabled',
       analytics: 'enabled',
     },
+    // Beta features (controlled rollout)
     beta: {
       newUI: 'coming_soon', // Ready for testing but not fully rolled out
       experimental: 'hidden',
@@ -61,18 +173,42 @@ export const featureConfig: FeatureFlagConfig = {
 
   // Production environment - stable features only
   production: {
+    // Core platform features (stable)
+    platform: {
+      dashboard: 'enabled',
+      leagues: 'enabled',
+      teams: 'enabled',
+      drivers: 'enabled',
+      races: 'enabled',
+      leaderboards: 'enabled',
+    },
+    // Authentication & onboarding (stable)
+    auth: {
+      signup: 'enabled',
+      login: 'enabled',
+      forgotPassword: 'enabled',
+      resetPassword: 'enabled',
+    },
+    onboarding: {
+      wizard: 'enabled',
+    },
+    // Sponsor features (gradual rollout)
     sponsors: {
       portal: 'enabled',
       dashboard: 'enabled',
       management: 'disabled', // Feature not ready yet
+      campaigns: 'enabled',
+      billing: 'enabled',
     },
+    // Admin features (stable)
     admin: {
       dashboard: 'enabled',
       userManagement: 'enabled',
       analytics: 'disabled', // Feature not ready yet
     },
+    // Beta features (controlled rollout)
     beta: {
-      newUI: 'disabled',
+      newUI: 'disabled', // Not ready for production
       experimental: 'hidden',
     },
   },