Configuration Consolidation - Unify 5 Config Systems into Single Canonical System

🎯 Objective

Consolidate 5 competing configuration systems into a single canonical configuration manager to eliminate duplication, improve maintainability, and establish a single source of truth for all configuration.

📊 Current State Analysis

Problem: Configuration is fragmented across multiple systems:

• src/config.py
• src/unified_config.py
• src/config_helper.py
• src/config_consolidated.py
• src/unified_config_manager.py

Impact:

• Backend: 235+ direct os.getenv() calls scattered across codebase
• Frontend: 40 files with direct import.meta.env or process.env access
• Confusion about which config system to use
• No type safety or validation
• Difficult to test (need to mock env vars in 235+ places)

✅ Success Criteria

• [ ] Single canonical config system chosen and documented
• [ ] All 5 config systems analyzed - features inventoried
• [ ] Best implementation selected based on code quality, type safety, validation
• [ ] All features preserved from all 5 systems (no feature loss)
• [ ] 235+ os.getenv() calls migrated to cfg.get() pattern
• [ ] 40+ frontend files migrated to centralized config service
• [ ] Type safety implemented with validation framework
• [ ] Tests updated to use single config mock
• [ ] Documentation updated with usage examples

📈 Expected Impact

Code Reduction: ~500-800 lines
Files Affected: ~280 files system-wide
Maintenance Burden: -70% (change config in 1 place, not 280)

🚀 Implementation Plan

Phase 1: Backend Consolidation (Week 1)

1. Inventory all features from 5 config systems
2. Analyze each system - choose best base implementation
3. Document selection rationale
4. Port all features to chosen system
5. Create migration script for os.getenv() → cfg.get()
6. Migrate backend files in batches
7. Update tests
8. Deprecate old config files

Phase 2: Frontend Standardization (Week 2)

1. Create TypeScript config service
2. Migrate 40 files from import.meta.env → useConfig()
3. Type-safe config access with validation
4. Consistent NetworkConstants usage
5. Update frontend tests

Phase 3: Validation & Cleanup (Week 3)

1. Schema validation for all config
2. Environment-specific config files
3. Integration tests
4. Documentation
5. Remove deprecated config files
6. Team training on new system

📋 Feature Preservation Checklist

From config.py:

• [ ] LLM config management
• [ ] Redis config
• [ ] Backend config
• [ ] Service URL generation
• [ ] CORS origins

From unified_config.py:

• [ ] Type safety
• [ ] Validation framework
• [ ] Environment variable substitution
• [ ] Timeout management

From config_helper.py:

• [ ] Helper utilities
• [ ] Path management

From config_consolidated.py:

• [ ] Consolidated defaults

From unified_config_manager.py:

• [ ] Manager patterns

📚 References

• CLAUDE.md - Consolidation & Refactoring Standards
• Memory MCP: "Configuration Consolidation Opportunity 2025-11"
• Related: #TBD (File Naming Audit)

🏷️ Labels

refactor, configuration, high-impact, technical-debt

⏱️ Estimate

3 weeks (15 person-days)