---
name: configuration-management
description: Configuration management patterns for GoodGo microservices including feature flags, dynamic configuration reloading, environment-specific configurations, and secrets management.
---

# Configuration Management Patterns

## When to Use This Skill

Use this skill when:
- Implementing feature flags and feature toggles
- Managing environment-specific configurations
- Implementing dynamic configuration reloading
- Managing secrets and sensitive configuration
- Implementing configuration validation

## Key Patterns

### Configuration Loading Flow

The configuration loading process fetches configuration from multiple sources, validates it, and supports dynamic reloading:

```mermaid
flowchart TD
    Start([Application Startup]) --> LoadConfig[Load Configuration]
    LoadConfig --> FetchSource{Fetch from Source}
    
    FetchSource --> |Environment Variables| EnvVars[Read Env Vars]
    FetchSource --> |Config Files| ConfigFiles[Read JSON/YAML]
    FetchSource --> |Database| Database[Query Config Table]
    FetchSource --> |External Service| ExternalService[Call Config API]
    
    EnvVars --> Validate[Validate with Zod Schema]
    ConfigFiles --> Validate
    Database --> Validate
    ExternalService --> Validate
    
    Validate --> |Valid| StoreConfig[Store in Memory Map]
    Validate --> |Invalid| LogError[Log Validation Error]
    LogError --> ThrowError[Throw Error]
    ThrowError --> End([Application Fails to Start])
    
    StoreConfig --> CheckChange{Value Changed?}
    CheckChange --> |Yes| EmitEvent[Emit 'config-changed' Event]
    CheckChange --> |No| SkipEvent[Skip Event]
    
    EmitEvent --> Ready[Configuration Ready]
    SkipEvent --> Ready
    Ready --> End
    
    Ready --> AutoReload{Auto-Reload Enabled?}
    AutoReload --> |Yes| SetInterval[Set Interval Timer]
    AutoReload --> |No| End
    SetInterval --> Wait[Wait Interval]
    Wait --> LoadConfig
```

### Feature Flag Evaluation Flow

Feature flags support multiple evaluation strategies including global flags, user-specific flags, and percentage-based rollouts:

```mermaid
flowchart TD
    Start([Check Feature Flag]) --> GetFlag[Get Flag by Key]
    GetFlag --> FlagExists{Flag Exists?}
    
    FlagExists --> |No| ReturnFalse[Return false]
    ReturnFalse --> End([End])
    
    FlagExists --> |Yes| CheckEnabled{Flag Enabled?}
    CheckEnabled --> |No| ReturnFalse
    
    CheckEnabled --> |Yes| HasUserId{User ID Provided?}
    HasUserId --> |No| ReturnTrue[Return true]
    ReturnTrue --> End
    
    HasUserId --> |Yes| CheckUserSpecific{User-Specific Flag?}
    CheckUserSpecific --> |Yes| MatchUser{User ID Matches?}
    MatchUser --> |Yes| ReturnTrue
    MatchUser --> |No| CheckPercentage
    
    CheckUserSpecific --> |No| CheckPercentage{Percentage Rollout?}
    CheckPercentage --> |No| ReturnTrue
    
    CheckPercentage --> |Yes| HashUser[Hash User ID]
    HashUser --> CalcHash[Calculate Hash % 100]
    CalcHash --> CompareHash{Hash < Percentage?}
    
    CompareHash --> |Yes| ReturnTrue
    CompareHash --> |No| ReturnFalse
```

### Feature Flags

```typescript
// Check if feature is enabled
const enabled = await featureFlagService.isEnabled('new-feature', userId);

if (enabled) {
  // Use new feature
}
```

### Dynamic Configuration

```typescript
// Load and auto-reload configuration
await configService.load();
configService.startAutoReload(60000); // Reload every minute

const value = configService.get('config-key', 'default-value');
```

### Configuration Validation

```typescript
// Validate with Zod
const config = validateConfig(process.env);
```

## Best Practices

1. Always validate configuration at startup
2. Provide sensible defaults
3. Never commit secrets to code
4. Use feature flags for gradual rollouts

## Resources

- [Feature Flags Pattern](https://martinfowler.com/articles/feature-toggles.html)
- Skill Source: `.cursor/skills/configuration-management/SKILL.md`
