metabuilder/frontends/codegen/docs/history/REFACTOR_PHASE3.md

Phase 3 Refactoring: JSON-Driven Architecture & Hook Library

Overview

This refactoring phase introduces a JSON-driven page orchestration system and comprehensive hook library to reduce component complexity and improve maintainability.

Goals

1. All components under 150 LOC - Break down monolithic components
2. Comprehensive hook library - Extract all business logic into reusable hooks
3. JSON-driven page orchestration - Define pages, actions, and data flows in JSON
4. Type-safe architecture - Full TypeScript support for JSON schemas

Architecture

1. Hook Library Structure

src/hooks/
├── core/                    # Core functionality
│   ├── use-clipboard.ts
│   ├── use-debounced-save.ts
│   ├── use-kv-state.ts
│   ├── use-local-storage.ts
│   └── use-persisted-state.ts
├── data/                    # Data management
│   ├── use-files.ts
│   ├── use-models.ts
│   ├── use-components.ts
│   ├── use-workflows.ts
│   ├── use-lambdas.ts
│   ├── use-tests.ts
│   └── use-project.ts
├── ui/                      # UI state management
│   ├── use-confirmation.ts
│   ├── use-dialog.ts
│   ├── use-selection.ts
│   ├── use-modal.ts
│   ├── use-tabs.ts
│   └── use-panels.ts
├── forms/                   # Form handling
│   ├── use-form-state.ts
│   ├── use-validation.ts
│   └── use-field-array.ts
├── canvas/                  # Canvas/visual editors
│   ├── use-canvas.ts
│   ├── use-drag-drop.ts
│   ├── use-zoom-pan.ts
│   └── use-connections.ts
├── ai/                      # AI operations
│   ├── use-ai-generate.ts
│   ├── use-ai-complete.ts
│   └── use-ai-suggestions.ts
└── orchestration/           # Page orchestration
    ├── use-page.ts
    ├── use-actions.ts
    └── use-json-schema.ts

2. JSON Page Schema

Each page is defined by a JSON schema that describes:

• Component tree structure
• Data sources and bindings
• Actions and event handlers
• Validation rules
• Initial/seed data

interface PageSchema {
  id: string
  name: string
  layout: LayoutConfig
  components: ComponentSchema[]
  data: DataSourceConfig[]
  actions: ActionConfig[]
  hooks: HookConfig[]
}

interface ComponentSchema {
  id: string
  type: string
  props: Record<string, any>
  children?: ComponentSchema[]
  bindings?: DataBinding[]
  events?: EventHandler[]
}

interface ActionConfig {
  id: string
  type: 'create' | 'update' | 'delete' | 'navigate' | 'ai-generate'
  trigger: string
  params: Record<string, any>
  onSuccess?: string
  onError?: string
}

3. Component Size Limits

• Atoms: < 50 LOC
• Molecules: < 100 LOC
• Organisms: < 150 LOC
• Features: < 150 LOC (orchestrated by JSON)

Implementation Plan

Phase 3.1: Hook Library Expansion

• Create data management hooks (use-files, use-models, etc.)
• Create form handling hooks
• Create canvas/visual editor hooks
• Create orchestration hooks

Phase 3.2: JSON Schema System

• Define TypeScript interfaces for page schemas
• Create schema validator
• Build page renderer from JSON
• Create schema builder UI

Phase 3.3: Component Breakdown

• Split FeatureIdeaCloud (currently 500+ LOC)
• Split ModelDesigner
• Split WorkflowDesigner
• Split ComponentTreeManager

Phase 3.4: Page Definitions

• Convert dashboard to JSON
• Convert code editor to JSON
• Convert model designer to JSON
• Convert all feature pages to JSON

Benefits

1. Maintainability: Smaller components are easier to test and modify
2. Reusability: Hooks can be used across multiple components
3. Flexibility: Pages can be modified without code changes
4. Type Safety: Full TypeScript support for schemas
5. Testing: Hooks and small components are easier to unit test
6. Documentation: JSON schemas serve as living documentation

Migration Strategy

1. Start with new features using JSON orchestration
2. Gradually refactor existing features
3. Keep old code working during transition
4. Add feature flags for rollout control

Next Steps

1. Review and approve this plan
2. Implement hook library (Phase 3.1)
3. Build JSON orchestration system (Phase 3.2)
4. Begin component refactoring (Phase 3.3)