Feature Flag System Migration: Legacy to Domain-Driven Architecture

SUPERSEDED — historical only. This document planned a migration onto Flipper, which #1409 has since removed entirely. The domains/ system is now backed by system.feature_flags + system.feature_flag_overrides with no gem involved, and any Flipper.* call below will raise NameError.

For how feature flags actually work, read Feature Flags.

The legacy parts/ analysis below is still accurate and is why the doc is kept.

Original status: Documentation Only - No implementation yet

This document outlines the migration strategy from the legacy feature flag system (in backend/parts/) to the new domain architecture (in backend/domains/), supporting three entity types (User, Tenant, Practitioner).

1. Legacy Feature Flag System SummaryCopy Anchor Link

1.1 Current EndpointsCopy Anchor Link

1.2 Legacy Database SchemaCopy Anchor Link

Table: public.basic_feature_flags (definition store)

Table: public.feature_flags (overrides)

1.3 Available Legacy Flags (19 total)Copy Anchor Link

App Visibility (5)

• SHOW_CMS_APP, SHOW_GROWTH_APP, SHOW_REPORTS_APP, SHOW_CONNECT_APP, SHOW_HOSPITAL_APP

Core Features (2)

• ENABLE_PACKAGES, ENABLE_GROWTH

Analytics & Reporting (2)

• ENABLE_REV_SHARE, ENABLE_COMMISSION_TRACKING

Experimental (1)

• ENABLE_BETA_FEATURES

Search (1)

• ENABLE_ADVANCED_SEARCH

Clinical Features (4)

• ENABLE_SURGERY, ENABLE_IPD, ENABLE_ABDM, ENABLE_WORKFLOWS

AI Features (1)

• ENABLE_AI_ASSISTANT

Scope note (#2505). #2505 retired these keys from the native system.feature_flags catalog only, where the domains encounter workflow now follows the practitioner's module entitlement instead. The legacy rows and constants documented in this section are untouched and still gate parts/ code (for example the dental examination API reads ENABLE_DENTAL_MODULE here).

Specialist Modules (3)

• ENABLE_PSYCHIATRIST_MODULE, ENABLE_PEDIATRICIAN_MODULE, ENABLE_DERMATOLOGIST_MODULE

1.4 Legacy Business RulesCopy Anchor Link

1. One Specialty Per Doctor: When enabling a specialist module (e.g., ENABLE_PEDIATRICIAN_MODULE), other specialist modules are automatically disabled for that doctor.

2. Authorization:

   • User flags: Requires authentication (via ApiController)
   • Clinic flags: Requires user.authorized_clinic?(clinic_id)
   • Doctor flags: Requires user.authorized_clinic?(clinic_id)

2. New Domain ArchitectureCopy Anchor Link

2.1 Architecture OverviewCopy Anchor Link

The new architecture uses:

• Flipper gem with PostgreSQL storage
• Domain-based schema (system., reference.)
• UUID primary keys
• Blueprinter for serialization
• Concern-based integration (FeatureFlaggable)

2.2 New Database SchemaCopy Anchor Link

Table: system.flipper_features (feature definitions)

Table: reference.flipper_gates (feature rules)

2.3 Entity Type MappingCopy Anchor Link

2.4 New API Endpoints (Admin Only)Copy Anchor Link

2.5 New Integration PatternCopy Anchor Link

# Include in any model
class User < Identity::BaseRecord
  include Identity::Concerns::FeatureFlaggable
end

# Usage
user = User.find(id)
user.has_feature?('SHOW_CMS_APP')        # Check if enabled
user.enable_feature!('SHOW_CMS_APP')      # Enable (admin)
user.disable_feature!('SHOW_CMS_APP')     # Disable (admin)

3. Gap AnalysisCopy Anchor Link

3.1 Comparison MatrixCopy Anchor Link

3.2 Missing ComponentsCopy Anchor Link

1. Public API for non-admin users - Need endpoints for users to read their flags
2. Category support - Flags should be categorizable (UI, Clinical, etc.)
3. Specialist module business logic - One specialty per doctor rule needs implementation
4. Legacy entity mapping - Need seamless mapping between Clinic→Tenant and ClinicDoctor→Practitioner

4. Proposed Domain DesignCopy Anchor Link

4.1 Domain StructureCopy Anchor Link

Create a new feature_flags domain or expand the existing system domain:

backend/domains/feature_flags/
├── models/
│   ├── feature_flag.rb           # Feature definition
│   ├── flag_assignment.rb        # Entity-to-flag mappings
│   └── concerns/
│       └── feature_flaggable.rb  # Already exists in Identity
├── controllers/
│   ├── feature_flags_controller.rb    # Admin management
│   ├── user_flags_controller.rb       # User-level flags
│   ├── tenant_flags_controller.rb     # Clinic-level flags
│   └── practitioner_flags_controller.rb # Doctor-level flags
├── services/
│   └── feature_flag_service.rb    # Shared business logic
├── interactor/
│   ├── list_flags.rb
│   ├── update_flag.rb
│   └── validate_specialist_rule.rb
├── blueprints/
│   ├── feature_flag_blueprint.rb
│   └── flag_assignment_blueprint.rb
└── routes.rb

4.2 Recommended Approach: Flipper-FirstCopy Anchor Link

Leverage Flipper's existing capabilities:

1. Feature definitions → system.flipper_features
2. Entity restrictions → reference.flipper_gates (entity_type gate)
3. Entity assignments → reference.flipper_gates (actors gate)
4. Categories → Add category field to FlipperFeature model
5. Metadata → Use Flipper's built-in storage or extend

5. API DesignCopy Anchor Link

5.1 New EndpointsCopy Anchor Link

5.2 Request/Response FormatsCopy Anchor Link

GET /users/:id/feature_flags

// Request
GET /users/019bd563-5763-7895-b971-07436bd3f2cc/feature_flags

// Response (200 OK)
{
  "data": {
    "entity_type": "User",
    "entity_id": "019bd563-5763-7895-b971-07436bd3f2cc",
    "flags": [
      {
        "key": "SHOW_CMS_APP",
        "enabled": true,
        "category": "app_visibility",
        "description": "Access to Clinical Management System",
        "is_default": false
      },
      {
        "key": "ENABLE_SURGERY",
        "enabled": false,
        "category": "clinical_modules",
        "description": "Enable surgery module",
        "is_default": false
      }
    ]
  }
}

PUT /users/:id/feature_flags/:key

// Request
PUT /users/019bd563-5763-7895-b971-07436bd3f2cc/feature_flags/SHOW_CMS_APP
Content-Type: application/json

{
  "enabled": true
}

// Response (200 OK)
{
  "success": true,
  "data": {
    "key": "SHOW_CMS_APP",
    "enabled": true,
    "entity_type": "User",
    "entity_id": "019bd563-5763-7895-b971-07436bd3f2cc"
  }
}

5.3 Authorization RulesCopy Anchor Link

6. Migration StrategyCopy Anchor Link

6.1 Backend ChangesCopy Anchor Link

Phase 1: Schema PreparationCopy Anchor Link

1. Add category field to system.flipper_features
2. Add seed data for existing 19 flags with proper entity types
3. Create migration script to copy legacy flag definitions

Phase 2: Controller ImplementationCopy Anchor Link

1. Create new domain controllers:
   • UserFeatureFlagsController (delegates to new architecture)
   • TenantFeatureFlagsController (for clinics)
   • PractitionerFeatureFlagsController (for doctors)
2. Update routes to point to new controllers
3. Implement authorization policies

Phase 3: Business LogicCopy Anchor Link

1. Implement FeatureFlagService with shared logic
2. Add specialist module rule (one per practitioner)
3. Add default value handling

Phase 4: DeprecationCopy Anchor Link

1. Keep legacy controllers as thin wrappers
2. Add deprecation warnings to legacy endpoints
3. Log migration progress

6.2 Data MigrationCopy Anchor Link

Step 1: Map Legacy Flags to New SchemaCopy Anchor Link

LEGACY_FLAG_MAPPING = {
  # User-level flags
  'SHOW_CMS_APP'        => { entity_type: 'User', category: 'app_visibility' },
  'SHOW_GROWTH_APP'     => { entity_type: 'User', category: 'app_visibility' },
  'SHOW_REPORTS_APP'    => { entity_type: 'User', category: 'app_visibility' },
  'SHOW_CONNECT_APP'    => { entity_type: 'User', category: 'app_visibility' },
  'SHOW_HOSPITAL_APP'   => { entity_type: 'User', category: 'app_visibility' },
  'ENABLE_BETA_FEATURES' => { entity_type: 'User', category: 'experimental' },

  # Tenant (Clinic)-level flags
  'ENABLE_PACKAGES'     => { entity_type: 'Tenant', category: 'core_features' },
  'ENABLE_GROWTH'       => { entity_type: 'Tenant', category: 'core_features' },
  'ENABLE_REV_SHARE'    => { entity_type: 'Tenant', category: 'analytics' },
  'ENABLE_COMMISSION_TRACKING' => { entity_type: 'Tenant', category: 'analytics' },
  'ENABLE_SURGERY'      => { entity_type: 'Tenant', category: 'clinical_modules' },
  'ENABLE_IPD'          => { entity_type: 'Tenant', category: 'clinical_modules' },
  'ENABLE_ABDM'         => { entity_type: 'Tenant', category: 'clinical_modules' },
  'ENABLE_WORKFLOWS'    => { entity_type: 'Tenant', category: 'clinical_modules' },
  'ENABLE_ADVANCED_SEARCH' => { entity_type: 'Tenant', category: 'search' },
  'ENABLE_AI_ASSISTANT' => { entity_type: 'Tenant', category: 'ai' },

  # Practitioner (ClinicDoctor)-level flags
  'ENABLE_PSYCHIATRIST_MODULE'    => { entity_type: 'Practitioner', category: 'specialist_modules' },
  'ENABLE_PEDIATRICIAN_MODULE'    => { entity_type: 'Practitioner', category: 'specialist_modules' },
  'ENABLE_DERMATOLOGIST_MODULE'   => { entity_type: 'Practitioner', category: 'specialist_modules' }
}

6.3 Frontend UpdatesCopy Anchor Link

API Service UpdatesCopy Anchor Link

Update /frontend/packages/auth/src/services/featureFlagsApi.ts:

const API = {
  // User flags
  getUserFlags: (userId: string) =>
    api.get(`/users/${userId}/feature_flags`),
  updateUserFlag: (userId: string, flagKey: string, enabled: boolean) =>
    api.put(`/users/${userId}/feature_flags/${flagKey}`, { enabled }),

  // Tenant (Clinic) flags
  getClinicFlags: (clinicId: string) =>
    api.get(`/tenants/${clinicId}/feature_flags`),
  updateClinicFlag: (clinicId: string, flagKey: string, enabled: boolean) =>
    api.put(`/tenants/${clinicId}/feature_flags/${flagKey}`, { enabled }),

  // Practitioner flags
  getDoctorFlags: (doctorId: string) =>
    api.get(`/practitioners/${doctorId}/feature_flags`),
  updateDoctorFlag: (doctorId: string, flagKey: string, enabled: boolean) =>
    api.put(`/practitioners/${doctorId}/feature_flags/${flagKey}`, { enabled })
}

7. Implementation TimelineCopy Anchor Link

Total Estimated: ~11 days

8. Risks & MitigationCopy Anchor Link

9. Key Files ReferenceCopy Anchor Link

Backend - New Architecture (Modify)Copy Anchor Link

Backend - Legacy (Deprecate)Copy Anchor Link

Frontend - ModifyCopy Anchor Link

10. ConclusionCopy Anchor Link

The migration from the legacy feature flag system to the new Flipper-based architecture is feasible and recommended because:

1. The new system already provides a solid foundation
2. Flipper is a well-maintained, production-ready gem
3. The entity mapping (User→User, Clinic→Tenant, ClinicDoctor→Practitioner) is already defined
4. The frontend can continue using existing hooks/components with minimal changes

Key work items:

1. Add missing capabilities (categories, public API)
2. Implement the new controllers and routes
3. Create the data migration script
4. Update frontend API calls