Skip to content

ARCHITECTURE_SIMPLIFICATION_PLAN.md

Latest commit

 

History

History
184 lines (149 loc) · 5.97 KB

ARCHITECTURE_SIMPLIFICATION_PLAN.md

File metadata and controls

184 lines (149 loc) · 5.97 KB

Architecture Simplification Implementation Plan

Phase 3: Architecture Simplification

Status: Ready for Implementation
Target: 40-50% reduction in codebase complexity while maintaining security and functionality

Implementation Priority

1. Provider System Consolidation (Week 1)

Target: Reduce 12 AuthTypes to 4 essential patterns

Consolidation Mapping:

// NEW: 4 Essential Auth Patterns
enum AuthProvider {
  GOOGLE_OAUTH = 'google-oauth',    // LOGIN_WITH_GOOGLE, USE_VERTEX_AI, CLOUD_SHELL
  API_KEY = 'api-key',             // USE_OPENAI, USE_ANTHROPIC, USE_GEMINI, USE_GROK, USE_RUNPOD
  LOCAL_HTTP = 'local-http',       // USE_OLLAMA, USE_LM_STUDIO
  LEGACY_OAUTH = 'legacy-oauth'    // QWEN_OAUTH (maintain backward compatibility)
}

interface ProviderConfig {
  type: AuthProvider;
  apiKey?: string;
  baseUrl?: string;
  model?: string;
  additionalConfig?: Record<string, unknown>;
}

Implementation Steps:

  1. Create ProviderManager class (packages/core/src/providers/ProviderManager.ts)
  2. Implement provider adapters for each auth pattern
  3. Migrate existing auth validation to new provider system
  4. Update credential management to use unified provider interface
  5. Maintain backward compatibility through provider adapters

2. Unified Configuration Management (Week 2)

Target: Single source of truth for all configuration

New Structure:

// packages/core/src/config/ConfigManager.ts
class ConfigManager {
  private providers: Map<string, ProviderConfig>;
  private toolRegistry: ToolRegistry;
  private settings: CoreSettings;
  
  // Unified configuration loading
  async loadConfiguration(source: ConfigSource): Promise<void>
  
  // Provider management
  getProvider(name: string): ProviderConfig
  setProvider(name: string, config: ProviderConfig): void
  
  // Tool configuration
  getToolConfig(): ToolConfig
  
  // Settings management
  getSetting<T>(key: string): T
  setSetting<T>(key: string, value: T): void
}

Migration Strategy:

  1. Create ConfigManager interface with provider abstraction
  2. Migrate settings from 3 config files to unified structure
  3. Implement configuration validation with schema validation
  4. Add configuration migration utilities for existing users
  5. Update all configuration consumers to use ConfigManager

3. Tool System Simplification (Week 3)

Target: 80% reduction in tool discovery complexity

Simplified Tool Architecture:

// Simplified tool interface
interface SimpleTool {
  name: string;
  description: string;
  schema: FunctionDeclaration;
  execute(params: Record<string, unknown>): Promise<ToolResult>;
}

// Unified tool registry
class UnifiedToolRegistry {
  private coreTools: Map<string, SimpleTool>;
  private discoveredTools: Map<string, SimpleTool>;
  
  registerCoreTool(tool: SimpleTool): void
  discoverExternalTools(): Promise<void>
  getTool(name: string): SimpleTool | undefined
  getAllTools(): SimpleTool[]
}

Implementation:

  1. Consolidate tool discovery mechanisms into single interface
  2. Simplify MCP tool integration with standardized adapter
  3. Reduce tool registry complexity by 80%
  4. Maintain tool functionality while simplifying discovery

4. Build System Optimization (Week 4)

Target: 3 essential commands replacing 30+ scripts

New Build Commands:

{
  "scripts": {
    "dev": "node scripts/dev.js",           // Development with watch mode
    "build": "node scripts/build.js",       // Production build
    "test": "node scripts/test.js"          // All testing (unit, integration, lint)
  }
}

Implementation:

  1. Analyze script dependencies and identify essential operations
  2. Create optimized build pipeline with parallel execution
  3. Consolidate testing workflows into single command
  4. Maintain development ergonomics while reducing complexity

Expected Benefits

Code Reduction Targets:

  • Provider System: 60% reduction in auth-related code
  • Configuration: 70% reduction in config management code
  • Tool System: 80% reduction in discovery mechanisms
  • Build Scripts: 60% reduction in build complexity

Maintainability Improvements:

  • Single source of truth for configuration
  • Unified provider interface reduces conditional logic
  • Simplified tool discovery reduces debugging complexity
  • Streamlined build process improves developer velocity

Security Enhancements:

  • Centralized credential management through ConfigManager
  • Reduced attack surface through code consolidation
  • Simplified validation logic reduces security bugs
  • Maintained security controls from previous phases

Success Metrics

Quantitative:

  • 40-50% reduction in total lines of code
  • 12 AuthTypes → 4 AuthProviders (67% reduction)
  • 3 config files → 1 ConfigManager (67% reduction)
  • 30+ build scripts → 3 commands (90% reduction)

Qualitative:

  • Single configuration entry point
  • Unified provider interface
  • Simplified tool discovery
  • Maintained backward compatibility
  • Enhanced developer experience

Risk Mitigation

Backward Compatibility:

  • Maintain existing API surface through adapters
  • Provide migration utilities for existing configurations
  • Support legacy auth types during transition period

Testing Strategy:

  • Comprehensive integration tests for new architecture
  • Migration testing with real-world configurations
  • Performance testing to ensure no regression
  • Security testing of new provider interfaces

Rollback Plan:

  • Feature flags for new architecture components
  • Gradual migration with fallback to existing system
  • Monitoring and alerting for migration issues
  • Documentation for rolling back changes

Timeline: 4 Weeks Total

Week 1: Provider System Consolidation
Week 2: Unified Configuration Management
Week 3: Tool System Simplification
Week 4: Build System Optimization

Each week includes implementation, testing, and documentation updates.