metabuilder/codegen/docs/history/REFACTOR_PHASE2.md

Phase 2 Refactoring Plan: Hooks, Components & JSON Orchestration

Goals

1. All components <150 LOC - Break down large feature components into composable pieces
2. Comprehensive Hook Library - Extract all business logic into reusable hooks
3. JSON-Based Page Orchestration - Define page layouts and feature configurations in JSON, loaded from database
4. Database-Driven UI - Store UI configurations, feature flags, and layouts in KV store

Hook Library Architecture

Core Hooks (/src/hooks/core/)

• use-kv-state.ts - Enhanced KV wrapper with validation
• use-debounced-save.ts - Debounced auto-save to KV
• use-undo-redo.ts - Undo/redo state management
• use-clipboard.ts - Copy/paste operations
• use-hotkeys.ts - Keyboard shortcut management

Feature Hooks (/src/hooks/features/)

• use-file-manager.ts - File CRUD operations
• use-model-manager.ts - Prisma model operations
• use-component-manager.ts - Component tree operations
• use-workflow-manager.ts - Workflow node operations
• use-lambda-manager.ts - Lambda function operations
• use-test-manager.ts - Test suite operations
• use-theme-manager.ts - Theme variant operations
• use-project-manager.ts - Project save/load/export
• use-idea-manager.ts - Feature idea cloud operations
• use-connection-manager.ts - Idea connections (1:1 mapping)

AI Hooks (/src/hooks/ai/)

• use-ai-generation.ts - Generic AI generation
• use-ai-code-improvement.ts - Code enhancement
• use-ai-explanation.ts - Code explanation
• use-ai-test-generation.ts - Test generation
• use-ai-model-suggestion.ts - Model field suggestions

UI Hooks (/src/hooks/ui/)

• use-dialog.ts - Dialog state management
• use-toast.ts - Toast notifications wrapper
• use-confirmation.ts - Confirmation dialogs
• use-selection.ts - Multi-select state
• use-drag-drop.ts - Drag and drop operations
• use-canvas-drawing.ts - Canvas drawing tools
• use-zoom-pan.ts - Canvas zoom/pan

Validation Hooks (/src/hooks/validation/)

• use-form-validation.ts - Form validation
• use-code-validation.ts - Code syntax validation
• use-schema-validation.ts - Schema validation

Component Size Breakdown

Large Components to Split (Current → Target LOC)

FeatureIdeaCloud.tsx (829 LOC → <150 each)

Split into:

• IdeaCanvas.tsx (80 LOC) - Canvas rendering
• IdeaCard.tsx (70 LOC) - Individual idea node
• IdeaConnection.tsx (60 LOC) - Arrow rendering
• IdeaToolbar.tsx (50 LOC) - Tool controls
• IdeaColorPicker.tsx (40 LOC) - Color selection
• IdeaGroupBoundary.tsx (60 LOC) - Group container

App.tsx (828 LOC → <150 each)

Split into:

• AppShell.tsx (100 LOC) - Main layout
• PageRouter.tsx (80 LOC) - Tab routing logic
• ExportDialog.tsx (120 LOC) - Export functionality
• Hooks: use-app-state.ts, use-export.ts

CodeEditor.tsx (~400 LOC → <150 each)

Split into:

• EditorTabs.tsx (80 LOC) - Tab bar
• EditorMonaco.tsx (100 LOC) - Monaco wrapper
• EditorToolbar.tsx (60 LOC) - Action buttons
• EditorAIPanel.tsx (90 LOC) - AI features

ModelDesigner.tsx (~350 LOC → <150 each)

Split into:

• ModelList.tsx (80 LOC) - Model list
• ModelEditor.tsx (120 LOC) - Field editor
• ModelGraph.tsx (90 LOC) - Visual graph

WorkflowDesigner.tsx (~500 LOC → <150 each)

Split into:

• WorkflowCanvas.tsx (120 LOC) - React Flow canvas
• WorkflowNodePalette.tsx (70 LOC) - Node types
• WorkflowNodeEditor.tsx (100 LOC) - Node config
• WorkflowToolbar.tsx (60 LOC) - Toolbar

JSON-Based Page Orchestration

Page Configuration Schema

interface PageConfig {
  id: string
  title: string
  description: string
  icon: string
  component: string
  layout: LayoutConfig
  features: FeatureConfig[]
  permissions?: string[]
  shortcuts?: KeyboardShortcut[]
}

interface LayoutConfig {
  type: 'single' | 'split' | 'grid' | 'tabs'
  panels?: PanelConfig[]
  direction?: 'horizontal' | 'vertical'
  defaultSizes?: number[]
}

interface PanelConfig {
  id: string
  component: string
  props?: Record<string, any>
  minSize?: number
  maxSize?: number
}

interface FeatureConfig {
  id: string
  enabled: boolean
  config?: Record<string, any>
}

Example Page Definitions

{
  "pages": [
    {
      "id": "code-editor",
      "title": "Code Editor",
      "description": "Edit project files with AI assistance",
      "icon": "Code",
      "component": "CodeEditorPage",
      "layout": {
        "type": "split",
        "direction": "horizontal",
        "defaultSizes": [20, 80],
        "panels": [
          {
            "id": "file-tree",
            "component": "FileExplorer",
            "minSize": 15,
            "maxSize": 40
          },
          {
            "id": "editor",
            "component": "CodeEditor",
            "minSize": 60
          }
        ]
      },
      "features": [
        { "id": "ai-improve", "enabled": true },
        { "id": "ai-explain", "enabled": true },
        { "id": "syntax-validation", "enabled": true }
      ],
      "shortcuts": [
        { "key": "2", "ctrl": true, "action": "navigate" }
      ]
    },
    {
      "id": "idea-cloud",
      "title": "Feature Ideas",
      "description": "Brainstorm and connect ideas",
      "icon": "Lightbulb",
      "component": "IdeaCloudPage",
      "layout": {
        "type": "single"
      },
      "features": [
        { "id": "connections", "enabled": true },
        { "id": "groups", "enabled": true },
        { "id": "colors", "enabled": true }
      ]
    }
  ]
}

Database-Driven UI

KV Store Structure

ui-config:{page-id} → PageConfig
feature-toggles:{feature-id} → boolean
layout-state:{page-id} → LayoutState
user-preferences → UserPreferences

Implementation Files

/src/config/
  ├── page-registry.ts       # Component name → React component mapping
  ├── default-pages.json     # Default page configurations
  └── page-schema.ts         # Zod schemas for validation

/src/hooks/config/
  ├── use-page-config.ts     # Load page config from KV
  ├── use-layout-state.ts    # Persist layout state
  └── use-feature-flags.ts   # Feature flag management

/src/components/layout/
  ├── PageOrchestrator.tsx   # Renders pages from JSON config
  ├── DynamicLayout.tsx      # Renders layouts from config
  └── DynamicPanel.tsx       # Renders panels from config

Migration Strategy

Phase 2.1: Hook Extraction (Week 1)

1. Create hook library structure
2. Extract business logic from top 5 largest components
3. Add comprehensive tests for hooks
4. Update components to use hooks

Phase 2.2: Component Splitting (Week 2)

1. Split FeatureIdeaCloud into 6 components
2. Split App.tsx into 3 components + hooks
3. Split CodeEditor into 4 components
4. Ensure all new components <150 LOC

Phase 2.3: JSON Orchestration (Week 3)

1. Create page config schema and defaults
2. Build PageOrchestrator and DynamicLayout
3. Create component registry
4. Migrate 3 pages to JSON config

Phase 2.4: Database Integration (Week 4)

1. Store page configs in KV
2. Add UI for editing page layouts
3. Feature flag management UI
4. User preference persistence

Success Criteria

• All components <150 LOC
• 30+ hooks in organized library
• 5+ pages driven by JSON config
• Page configs stored in KV database
• Zero business logic in components (all in hooks)
• All tests passing
• Documentation for hook library
• Migration guide for developers

Benefits

1. Maintainability: Smaller components easier to understand and modify
2. Reusability: Hooks can be used across multiple components
3. Testability: Hooks and small components easier to test in isolation
4. Flexibility: JSON configs allow runtime UI changes without code deploys
5. Scalability: Easy to add new pages/features via JSON
6. Safety: Smaller changes reduce risk of breaking existing features