Flag Hierarchy

Organizing and structuring feature flags for better management and maintainability

What is Flag Hierarchy?

Flag hierarchy in FlagFlow allows you to organize feature flags in a nested, tree-like structure using forward slashes as separators. This organizational system helps manage large numbers of flags by grouping related functionality and creating logical namespaces.

Key Concept: Hierarchical flags use path-like naming (e.g., ui/dashboard/new_layout) to create organized, searchable, and maintainable flag structures.

Hierarchy Structure Examples

Here are practical examples of how flag hierarchy can organize your feature flags:

Hierarchical Flag Organization

// Feature-based hierarchy
ui/dashboard/new_layout: boolean
ui/dashboard/dark_mode: boolean
ui/sidebar/collapsible: boolean
ui/sidebar/quick_actions: boolean

// Service-based hierarchy
api/auth/oauth2_enabled: boolean
api/auth/session_timeout: number
api/payment/stripe_enabled: boolean
api/payment/max_retry_attempts: number

// Environment-specific hierarchy
experiments/checkout/ab_test_flow: "A" | "B"
experiments/pricing/discount_banner: boolean
experiments/search/ai_suggestions: boolean

// Team-based hierarchy
marketing/campaigns/holiday_banner: boolean
marketing/analytics/conversion_tracking: boolean
devops/monitoring/detailed_logging: boolean
devops/performance/cache_enabled: boolean

Pros and Cons of Flag Hierarchy

✅ Advantages

Selective Access: You can access specific parts of the hierarchy without loading the entire flag set, improving performance
Logical Grouping: Group related flags together for easier management and understanding (e.g., all UI flags under ui/)
Clear Structure: Hierarchical paths show relationships and dependencies between features visually
Easier Navigation: Tree-like structure makes finding specific flags faster in large codebases
Team Organization: Different teams can own different branches of the hierarchy independently
Bulk Operations: Apply changes or permissions to entire hierarchy branches at once

⚠️ Better to Avoid

Over-nesting: Keep hierarchies shallow (2-3 levels) to maintain simplicity and readability
Inconsistent naming: Establish clear naming conventions early and document them for your team
Premature organization: Start simple and evolve hierarchy as your flag usage patterns become clear
Mixing organizational schemes: Choose one approach per branch (by feature, by team, etc.) and stick to it
Frequent restructuring: Plan hierarchy changes carefully and communicate them well to minimize disruption

Selective Access Benefits

One of the key advantages of flag hierarchy is the ability to access specific portions of your flag tree without loading the entire configuration:

Selective Flag Access

// Access only UI-related flags
const uiFlags = await flagClient.getFlags('ui');
// Returns: ui/dashboard/*, ui/sidebar/*, etc.

// Access only dashboard-specific flags  
const dashboardFlags = await flagClient.getFlags('ui/dashboard');
// Returns: ui/dashboard/new_layout, ui/dashboard/dark_mode

// Access a specific flag directly (constant from generated TS code)
const newLayout = await flagClient.getFlag('ui/dashboard/new_layout');

// Access multiple related flags efficiently
const experimentFlags = await flagClient.getFlags('experiments');
// Returns all experiment flags without loading API or UI flags

Performance Benefits

Reduced network traffic by fetching only needed flag subsets
Faster application startup when loading specific feature areas
Lower memory usage by avoiding unused flag data
Improved cache efficiency with targeted flag updates

Effective Grouping Strategies

Recommended Grouping Approaches

By Application Area

Area-based Organization

ui/header/search_enabled
ui/footer/social_links
api/auth/rate_limiting
api/database/connection_pool
notifications/email/enabled
notifications/push/badge_count

By Team Ownership

Team-based Organization

frontend/dashboard/widgets
frontend/mobile/responsive
backend/payments/processor
backend/analytics/tracking
devops/monitoring/alerts
devops/deployment/canary

❌ By Feature Lifecycle (Not Recommended)

Obsolete approach: Organizing by lifecycle stages is not the proper way as it creates artificial boundaries that don't reflect actual feature relationships.

Lifecycle-based Organization (Don't Use)

# Avoid this pattern
stable/core/authentication
stable/billing/invoices
experimental/ai/suggestions
experimental/social/sharing
deprecated/legacy/old_ui
deprecated/v1/api_endpoints

❌ By Environment Context (Not Recommended)

Wrong approach: You should install one FlagFlow instance per environment rather than organizing flags by environment within a single instance.

Environment-based Organization (Don't Use)

# Avoid this pattern - use separate FlagFlow instances instead
production/performance/caching
production/security/encryption
development/debug/logging
development/testing/mock_data
staging/integration/external_apis
staging/qa/feature_testing

TypeScript Integration with Hierarchy

FlagFlow's TypeScript integration provides full IntelliSense support for hierarchical flags. All flag path constants are automatically generated from your TypeScript interface:

TypeScript Hierarchy Support

// Generated TypeScript interface maintains hierarchy
export interface FLAGS {
  'ui/dashboard/new_layout': boolean;
  'ui/dashboard/dark_mode': boolean;
  'ui/sidebar/collapsible': boolean;
  'api/auth/oauth2_enabled': boolean;
  'api/auth/session_timeout': number;
  'experiments/checkout/ab_test_flow': "A" | "B";
}

// Type-safe flag access with autocompletion (constants from generated TS code)
const dashboardLayout = getFlagValue('ui/dashboard/new_layout');
//                                    ↑ Full IntelliSense support from FLAGS interface

// Bulk access with type safety (path prefixes from generated constants)
const uiFlags = getFlags('ui'); // Returns UI flags with correct types
const authFlags = getFlags('api/auth'); // Returns auth flags

Generated Constants: All flag path strings like 'ui/dashboard/new_layout', 'api/auth/oauth2_enabled', etc. are automatically generated from your TypeScript FLAGS interface, ensuring type safety and preventing typos.

Hierarchy Best Practices

✅ Do's

Keep it shallow: Aim for 2-3 levels deep maximum for most use cases
Use consistent naming: Establish naming conventions and stick to them
Group by functionality: Related features should be in the same branch
Plan for growth: Design hierarchy with future expansion in mind
Document structure: Maintain documentation of your hierarchy organization

❌ Don'ts

Avoid over-nesting: Don't create unnecessary depth for simple flags
Don't use special characters: Stick to letters, numbers, and underscores
Avoid ambiguous names: Each level should clearly indicate its purpose
Don't mix organizational schemes: Be consistent within each branch
Avoid frequent restructuring: Plan changes carefully to minimize disruption

Hierarchy Migration Strategy

When introducing hierarchy to existing flat flag structures or reorganizing existing hierarchies:

Plan the new structure: Design your target hierarchy before making changes
Create aliases: Maintain backward compatibility during transition
Gradual migration: Move flags in batches rather than all at once
Update documentation: Keep team informed of structure changes
Monitor usage: Ensure all applications adapt to the new structure
Clean up aliases: Remove deprecated paths after migration is complete

Migration Example

// Example migration from flat to hierarchical structure

// Before: Flat structure
enable_dashboard_v2: boolean
enable_dark_mode: boolean
enable_sidebar_collapse: boolean
auth_oauth_enabled: boolean

// After: Hierarchical structure
ui/dashboard/v2_enabled: boolean
ui/theme/dark_mode: boolean  
ui/sidebar/collapsible: boolean
api/auth/oauth_enabled: boolean

// During migration: Support both (with aliases)
enable_dashboard_v2 → ui/dashboard/v2_enabled
enable_dark_mode → ui/theme/dark_mode

Performance Considerations

Optimization Tips

Load only required hierarchy branches
Use caching for frequently accessed flag groups
Implement lazy loading for deep hierarchies
Monitor flag access patterns to optimize structure

Monitoring Metrics

Track which hierarchy branches are accessed most
Monitor flag resolution times by depth
Measure memory usage of loaded flag subsets
Analyze network traffic patterns for hierarchy access

On this page