metabuilder/docs/refactoring/reference/REFACTORING_INDEX.md

MetaBuilder Component Refactoring Strategy - Complete Guide

Status: ✅ Strategy Complete - Ready for Implementation
Generated: December 25, 2025
Estimated Effort: 103 hours over 4 weeks

📖 Documentation Index

This guide addresses React component size violations in MetaBuilder. The project enforces a <150 LOC limit per component to maintain modularity and follow the data-driven architecture philosophy.

📑 Documents in This Series

Document	Purpose	Audience	Length
REFACTORING_SUMMARY.md	Executive overview and quick stats	Managers, Tech Leads	300 lines
REFACTORING_STRATEGY.md	Detailed technical blueprint	Developers, Architects	1,673 lines
REFACTORING_CHECKLIST.md	Implementation task list	Project Managers	484 lines
REFACTORING_QUICK_REFERENCE.md	Patterns, templates, pitfalls	Developers	857 lines

---

🎯 Quick Start

For Managers

1. Read REFACTORING_SUMMARY.md (5 min)
2. Review timeline and effort estimates
3. Allocate team resources for 4-week sprint
4. Approve database schema changes

For Tech Leads

1. Read REFACTORING_STRATEGY.md (30 min)
2. Review architecture decisions
3. Approve hook and component designs
4. Plan code review process

For Developers

1. Start with REFACTORING_QUICK_REFERENCE.md (15 min)
2. Deep dive into REFACTORING_STRATEGY.md for your assigned violation
3. Use REFACTORING_CHECKLIST.md as you implement
4. Reference patterns for similar components

For Architects

1. Review entire REFACTORING_STRATEGY.md
2. Evaluate database schema design
3. Validate hook API contracts
4. Assess multi-tenant implications

---

📊 At a Glance

The Problem

• 8 components exceed 150 LOC architectural limit
• Largest: GitHubActionsFetcher (887 LOC)
• Average: 569 LOC per violation
• Impact: Hard to test, maintain, and reuse

The Solution

• Component decomposition into focused, small components
• Custom hooks for business logic and data management
• Database persistence for state that survives reloads
• Lua scripts for complex, reusable operations
• Configuration as data instead of hardcoded values

The Outcome

BEFORE                      AFTER
────────────────────────────────────────
8 monoliths             →   40+ small components
569 LOC average         →   73 LOC average
5 custom hooks          →   20+ custom hooks
~10 Lua scripts         →   ~15 Lua scripts
Ephemeral state         →   Persistent database
Hardcoded config        →   JSON in database

---

🔍 Violations by Priority

Violation #1: GitHubActionsFetcher.tsx (887 LOC)

Target: 95 LOC | Effort: 28 hours | Timeline: Week 1

Responsibilities to split:

• GitHub API integration → useGitHubActions hook
• Log fetching → useWorkflowLogs hook
• Analysis → useWorkflowAnalysis hook
• UI rendering → 6 sub-components

Database models: 3 (WorkflowRun, Job, Config)

See: REFACTORING_STRATEGY.md - Violation #1

---

Violation #2: NerdModeIDE.tsx (733 LOC)

Target: 110 LOC | Effort: 30 hours | Timeline: Week 2

Responsibilities to split:

• File tree operations → useIDEFileTree hook
• Project management → useIDEProject hook
• File editing → useIDEEditor hook
• Git operations → useIDEGit hook
• Test execution → useIDETest hook
• UI rendering → 7 sub-components

Database models: 4 (Project, File, GitConfig, TestRun)

See: REFACTORING_STRATEGY.md - Violation #2

---

Violation #3: LuaEditor.tsx (686 LOC)

Target: 120 LOC | Effort: 25 hours | Timeline: Week 3

Responsibilities to split:

• Monaco config (60+ LOC) → LuaMonacoConfig component
• Script management → useLuaScripts hook
• Editor state → useLuaEditor hook
• Execution → useLuaExecution hook
• Security → useLuaSecurity hook
• UI rendering → 8 sub-components

Database models: 3 (Library, Parameter, TestRun)

See: REFACTORING_STRATEGY.md - Violation #3

---

🏗️ Architecture Pattern

Before (Monolithic)

Component.tsx (800+ LOC)
├── useState for everything (15+ hooks)
├── API calls inline
├── Business logic mixed with UI
├── Hardcoded configs
└── Lost on page reload

After (Modular, Data-Driven)

Component.tsx (100 LOC) - UI only
├── Sub1.tsx (60 LOC) - Sub-feature 1
├── Sub2.tsx (70 LOC) - Sub-feature 2
├── Sub3.tsx (50 LOC) - Sub-feature 3
│
Hooks (extracted)
├── useFeature1.ts - Data + logic
├── useFeature2.ts - Data + logic
└── useFeature3.ts - Data + logic
│
Database (persistent)
├── Model1 - Feature 1 state
├── Model2 - Feature 2 state
└── Model3 - Feature 3 state
│
Lua (reusable)
├── ComplexOperation1.lua
└── ComplexOperation2.lua

---

📈 Effort & Timeline

WEEK 1: GitHubActionsFetcher (28 hours)
├─ Mon: Database + API hook
├─ Tue-Wed: Log + Analysis hooks  
├─ Thu: Components (toolbar, list, jobs)
└─ Fri: Panel + Main component

WEEK 2: NerdModeIDE (30 hours)
├─ Mon: Database + Project hook
├─ Tue-Wed: Tree + Editor hooks
├─ Thu: File Tree + Panels
└─ Fri: Dialogs + Main component

WEEK 3: LuaEditor (25 hours)
├─ Mon: Config extraction + Hooks
├─ Tue: Parameter + Execution
├─ Wed: Security + Snippets
└─ Thu-Fri: Main component + Tests

WEEK 4: Validation (20 hours)
├─ Mon-Tue: Unit & Integration tests
├─ Wed: Code review & Optimization
├─ Thu: Staging & Documentation
└─ Fri: Production deploy

────────────────────────────────
TOTAL: 103 hours over 4 weeks

---

💾 Database Design Summary

New Models: 15 total

GitHub Feature (3):

• GitHubWorkflowRun - Workflow runs with cached data
• GitHubWorkflowJob - Job details and steps
• GitHubConfig - API credentials and settings

IDE Feature (4):

• IDEProject - Project metadata
• IDEFile - File tree with content
• GitConfig - Git repository config (shared)
• IDETestRun - Test execution results

Lua Feature (3):

• LuaScriptLibrary - Reusable code snippets
• LuaScriptParameter - Parameter definitions
• LuaTestRun - Execution history

Updated (1):

• LuaScript - Add description field

System (2):

• Tenant - Multi-tenant support
• User - Owner tracking

---

🪝 Custom Hooks Design

Data Fetching Hooks (3)

useGitHubActions()
useWorkflowLogs()
useWorkflowAnalysis()

File Management Hooks (5)

useIDEProject()
useIDEFileTree()
useIDEEditor()
useIDEGit()
useIDETest()

Lua Management Hooks (4)

useLuaScripts()
useLuaEditor()
useLuaExecution()
useLuaSecurity()

---

🧩 New Components: 25 total

GitHubActions (7)

1. GitHubActionsToolbar - Refresh, download controls
2. GitHubActionsRunsList - Workflow runs display
3. GitHubActionsRunRow - Single run item
4. GitHubActionsJobsPanel - Job and log display
5. GitHubActionsJobStep - Single step item
6. GitHubActionsAnalysisPanel - AI analysis results
7. GitHubActionsFetcher - Refactored orchestrator

NerdModeIDE (8)

1. IDEFileTreePanel - File tree with nodes
2. IDEFileTreeNode - Single file/folder item
3. IDEEditorPanel - Monaco editor with toolbar
4. IDEToolbar - File/project operations
5. IDEConsolePanel - Output and test results
6. IDEGitDialog - Git configuration
7. IDENewFileDialog - Create file dialog
8. NerdModeIDE - Refactored orchestrator

LuaEditor (10)

1. LuaScriptSelector - Script list
2. LuaCodeEditor - Monaco editor
3. LuaMonacoConfig - Editor configuration (60+ LOC extracted)
4. LuaParameterItem - Single parameter editor
5. LuaParametersPanel - Parameter list
6. LuaExecutionResult - Results display
7. LuaExecutionPanel - Execute script UI
8. LuaSecurityWarningDialog - Security warnings
9. LuaSnippetLibraryPanel - Code snippets
10. LuaEditor - Refactored orchestrator

---

🧪 Testing Strategy

Unit Tests

• Each custom hook with mocked database/API
• Isolated component testing with mocked props
• 80%+ code coverage

Component Tests

• Props validation
• User interactions (click, type)
• State changes
• Error handling

Integration Tests

• Hook + Component interaction
• Database persistence
• Multiple component composition

E2E Tests

• Full feature workflows
• Real API calls
• Complete user journeys

---

✅ Success Criteria

• All components < 150 LOC
• 80%+ test coverage
• Zero ESLint violations
• All database migrations completed
• All hooks fully typed
• All Lua scripts tested
• No performance regressions
• All E2E tests passing
• Complete documentation

---

🚀 Getting Started

Step 1: Preparation

1. Review REFACTORING_STRATEGY.md with team
2. Approve database schema
3. Set up testing environment
4. Create GitHub issues from checklist

Step 2: Implementation (Week 1-3)

1. Follow the 3-week implementation plan
2. Use REFACTORING_CHECKLIST.md for tracking
3. Reference REFACTORING_QUICK_REFERENCE.md for patterns
4. Complete weekly code reviews

Step 3: Validation (Week 4)

1. Run full test suite
2. Performance benchmarking
3. Code review and optimization
4. Documentation finalization

Step 4: Deployment

1. Staging environment testing
2. Team sign-off
3. Production deployment
4. Monitoring and support

---

📚 Related Resources

TODO: Paths below are wrong from docs/refactoring; update copilot/PRD and schema/src references to valid locations.

• copilot-instructions.md - MetaBuilder architecture guide
• PRD.md - Product requirements
• prisma/schema.prisma - Current database schema
• src/hooks/ - Existing hook examples
• src/components/ - Component examples

---

🤝 Contributing

When implementing this strategy:

1. Follow the checklist - Don't skip steps
2. Write tests first - TDD approach
3. Document as you go - Don't wait until the end
4. Ask questions - If unclear about design
5. Communicate progress - Weekly status updates
6. Code review thoroughly - Multiple eyes on changes

---

📞 Questions?

Question	Document	Section
"What's the total effort?"	REFACTORING_SUMMARY.md	Effort Breakdown
"How do I structure hooks?"	REFACTORING_QUICK_REFERENCE.md	Hook API Patterns
"What are the pitfalls?"	REFACTORING_QUICK_REFERENCE.md	Common Pitfalls
"What's my task?"	REFACTORING_CHECKLIST.md	Your Violation
"Full technical details?"	REFACTORING_STRATEGY.md	Full Document

---

🎓 Key Principles

The strategy follows MetaBuilder's core philosophy:

1. Data-Driven - Configuration in database/JSON, not code
2. Modular - Small, focused components with clear boundaries
3. Reusable - Hooks for logic, Lua for runtime-modifiable operations
4. Testable - Each piece independently testable
5. Persistent - State survives page reloads via database
6. Multi-tenant - Database schema supports multiple tenants

---

📋 Document Checklist

• Summary of violations identified
• Detailed refactoring plan for each violation
• Database schema design
• Hook API specifications
• Component decomposition plan
• Lua script definitions
• Testing strategy
• Implementation checklist
• Quick reference guide
• Timeline and effort estimates
• Risk mitigation strategies
• Success criteria

---

Version: 1.0
Status: Ready for Implementation ✅
Last Updated: December 25, 2025
Total Documentation: 3,600+ lines

Next Step: Discuss with team and begin Week 1 implementation! 🚀