mirror of
https://github.com/johndoe6345789/metabuilder.git
synced 2026-04-25 14:25:02 +00:00
19 KiB
19 KiB
Visual Architecture Diagrams
Component Architecture Before & After
GitHubActionsFetcher: Before (887 LOC)
┌─────────────────────────────────────────────┐
│ GitHubActionsFetcher.tsx (887 LOC) │
├─────────────────────────────────────────────┤
│ ┌─ State (8+ hooks) │
│ │ - data: WorkflowRun[] │
│ │ - isLoading: boolean │
│ │ - error: string | null │
│ │ - selectedRunId: number | null │
│ │ - runJobs: Job[] │
│ │ - runLogs: string | null │
│ │ - analysis: string | null │
│ │ - autoRefreshEnabled: boolean │
│ │ │
│ ├─ Fetch Logic (100+ LOC) │
│ │ - fetchGitHubActions() │
│ │ - downloadRunLogs() │
│ │ - downloadWorkflowData() │
│ │ - analyzeWorkflows() │
│ │ - analyzeRunLogs() │
│ │ │
│ ├─ Utilities (50+ LOC) │
│ │ - getStatusColor() │
│ │ - getStatusIcon() │
│ │ - useEffect hooks (polling, etc) │
│ │ │
│ └─ UI Rendering (300+ LOC) │
│ - Tabs (3) │
│ - Cards (10+) │
│ - Lists, Buttons, etc. │
└─────────────────────────────────────────────┘
GitHubActionsFetcher: After (95 LOC)
┌────────────────────────────────────────────────────────────────┐
│ GitHubActionsFetcher.tsx (95 LOC - Orchestrator) │
├────────────────────────────────────────────────────────────────┤
│ const { runs, isLoading } = useGitHubActions() │
│ const [selectedRunId, setSelectedRunId] = useState(null) │
│ │
│ return ( │
│ <Tabs> │
│ <GitHubActionsToolbar {...props} /> │
│ <GitHubActionsRunsList {...props} /> │
│ <GitHubActionsJobsPanel {...props} /> │
│ <GitHubActionsAnalysisPanel {...props} /> │
│ </Tabs> │
│ ) │
└────────────────────────────────────────────────────────────────┘
│ │ │
▼ ▼ ▼
┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐
│ GitHubActions │ │ GitHubActions │ │ GitHubActions │
│ Toolbar │ │ RunsList │ │ JobsPanel │
│ (65 LOC) │ │ (80 LOC) │ │ (100 LOC) │
└──────────────────┘ └──────────────────┘ └──────────────────┘
│ │ │
└────────────────────────┼─────────────────────┘
│
Uses: useGitHubActions()
useWorkflowLogs()
useWorkflowAnalysis()
Data Flow Architecture
Current (Monolithic)
┌─────────────────────────────────────┐
│ User Action │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ Component setState │
│ (Lost on reload) │
└────────────────┬────────────────────┘
│
▼
┌─────────────────────────────────────┐
│ UI Render │
│ (300+ LOC mixed concerns) │
└─────────────────────────────────────┘
Refactored (Data-Driven)
┌─────────────────────────────────┐
│ User Action │
└────────────┬────────────────────┘
│
▼
┌────────────────────────────────────────┐
│ Custom Hook (useGitHubActions) │
├────────────────────────────────────────┤
│ - API Call │
│ - Error Handling │
│ - Cache Management │
└────────────┬───────────────────────────┘
│
┌───────┴────────┐
│ │
▼ ▼
┌──────────┐ ┌──────────────┐
│ Database │ │ React State │
│ (Persist)│ │ (UI only) │
└──────────┘ └──────────────┘
│ │
└───────┬────────┘
│
▼
┌──────────────────────┐
│ Component Render │
│ (95 LOC, clean) │
└──────────────────────┘
Database Schema Relationships
GitHub Feature
┌──────────────────────────┐
│ GitHubConfig │
│ (API credentials) │
└──────────────┬───────────┘
│ (1:N)
▼
┌──────────────────────────────┐
│ GitHubWorkflowRun │
│ - id │
│ - name, status, conclusion │
│ - htmlUrl, headBranch │
│ - jobsData (JSON) │
│ - logsData (cached) │
│ - analysisCache (AI result) │
└──────────────┬───────────────┘
│ (1:N)
▼
┌──────────────────────────────┐
│ GitHubWorkflowJob │
│ - id, githubJobId │
│ - name, status, conclusion │
│ - stepsJson (array) │
└──────────────────────────────┘
IDE Feature
┌──────────────────────────┐
│ IDEProject │
│ - id, name, ownerId │
│ - createdAt, updatedAt │
└──────────────┬───────────┘
┌─────────┼─────────┐
│ │ │
(1:N) (1:N) (1:1)
│ │ │
▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐
│IDEFile │ │IDETest │ │GitConfig
│(tree) │ │Run │ │
└────────┘ └────────┘ └────────┘
│
(1:N)
parent
│
▼
┌────────┐
│IDEFile │ (children)
│(nested)│
└────────┘
Lua Feature
┌──────────────────────────────┐
│ LuaScriptLibrary │
│ - id, name, code │
│ - category, parameters │
└──────────────┬───────────────┘
│ (1:N)
▼
┌──────────────────────────────┐
│ LuaScriptParameter │
│ - name, type, defaultValue │
└──────────────────────────────┘
┌──────────────────────────────┐
│ LuaScript │
│ (from existing model) │
└──────────────┬───────────────┘
│ (1:N)
▼
┌──────────────────────────────┐
│ LuaTestRun │
│ - timestamp, inputsJson │
│ - outputJson, executionTime │
└──────────────────────────────┘
Hook Composition Pattern
For Complex Features (3+ responsibilities)
┌──────────────────────────┐
│ Component (UI only) │
│ <100 LOC │
└────────┬────────┬────────┘
│ │
▼ ▼
┌──────────┬──────────┐
│ Hook 1 │ Hook 2 │
│ (Logic) │ (Logic) │
└──┬───────┴───┬──────┘
│ │
└─────┬─────┘
▼
┌─────────┐
│Database │
│ (State) │
└─────────┘
Example: GitHubActionsFetcher
Component (95 LOC)
│ │ │
▼ ▼ ▼
useGitHubActions
useWorkflowLogs
useWorkflowAnalysis
│ │ │
└──────┴──────┘
▼
Database
(Prisma models)
Component Hierarchy
GitHubActionsFetcher Tree
GitHubActionsFetcher (95 LOC)
├── GitHubActionsToolbar (65 LOC)
│ ├── Button (Refresh)
│ ├── Button (Download)
│ └── Toggle (Auto-refresh)
│
├── TabsList
│ ├── Tab (Runs)
│ ├── Tab (Logs)
│ └── Tab (Analysis)
│
├── TabsContent (Runs)
│ └── GitHubActionsRunsList (80 LOC)
│ ├── GitHubActionsRunRow (45 LOC)
│ │ ├── Badge (status)
│ │ ├── Text (workflow name)
│ │ └── Button (download logs)
│ └── GitHubActionsRunRow (45 LOC)
│ └── ...
│
├── TabsContent (Logs)
│ └── GitHubActionsJobsPanel (100 LOC)
│ ├── JobsList
│ │ └── GitHubActionsJobStep (50 LOC)
│ │ ├── Icon (status)
│ │ ├── Text (step name)
│ │ └── Badge (duration)
│ └── ScrollArea (logs)
│
└── TabsContent (Analysis)
└── GitHubActionsAnalysisPanel (70 LOC)
├── Button (Analyze)
└── Card (results)
State Management Pattern
Before: All in Component
Component State:
- data: WorkflowRun[] (from API)
- isLoading: boolean
- error: string | null
- selectedRunId: number | null
- runJobs: Job[] (from API)
- runLogs: string | null (from API)
- analysis: string | null (from LLM)
- isAnalyzing: boolean
Total: 8+ useState calls
All lost on page reload
Can't share with other components
After: Separated Concerns
Database (Persistent):
✓ WorkflowRun
✓ WorkflowJob
✓ GitHubConfig
React State (Ephemeral UI):
✓ selectedRunId (local selection)
✓ showDialog (modal open/close)
Custom Hooks (Derived):
✓ useGitHubActions() → { runs, isLoading, error }
✓ useWorkflowLogs() → { logs, isLoading }
✓ useWorkflowAnalysis() → { analysis, isAnalyzing }
Total: 3 useState + 3 hooks
Persistent across reloads
Shareable with other components
Refactoring Timeline Visualization
WEEK 1: GitHubActionsFetcher (28 hours)
│
├─ Mon (8h): 📊 Database + 🪝 API Hook
│ ├─ Create models
│ ├─ Migrations
│ └─ useGitHubActions
│
├─ Tue (4h): 🪝 Logs Hook
│ └─ useWorkflowLogs
│
├─ Wed (4h): 🪝 Analysis Hook
│ └─ useWorkflowAnalysis
│
├─ Thu (8h): 🧩 Components
│ ├─ GitHubActionsToolbar
│ ├─ GitHubActionsRunsList
│ ├─ GitHubActionsRunRow
│ └─ GitHubActionsJobsPanel
│
├─ Fri (4h): 🧩 Final Components + 🔄 Refactor
│ ├─ GitHubActionsJobStep
│ ├─ GitHubActionsAnalysisPanel
│ └─ Refactor main component to 95 LOC
│
└─ Testing: ✅ Unit + Component tests
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WEEK 2: NerdModeIDE (30 hours)
│
├─ Mon (8h): 📊 Database + 🪝 Project Hook
├─ Tue (6h): 🪝 File Tree Hook
├─ Wed (6h): 🪝 Editor + Git + Test Hooks
├─ Thu (8h): 🧩 Components (Tree + Editor)
├─ Fri (2h): 🧩 Final Components + Refactor
│
└─ Testing: ✅ Full integration
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WEEK 3: LuaEditor (25 hours)
│
├─ Mon (3h): 📊 Database updates
├─ Mon (2h): 🧩 Monaco Config extraction
├─ Tue (4h): 🪝 Hooks (Scripts, Editor, Exec, Security)
├─ Wed (8h): 🧩 Components (6)
├─ Thu (6h): 🧩 Final Components + Refactor
│
└─ Testing: ✅ Security focus
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
WEEK 4: Validation & Deploy (20 hours)
│
├─ Mon (4h): 🧪 Unit test fixes
├─ Tue (4h): 🧪 Integration tests
├─ Wed (4h): 🔍 Code review & Optimization
├─ Thu (4h): 📋 Documentation & Deploy prep
│
└─ Fri (4h): 🚀 Production deploy + Monitoring
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Legend:
📊 Database 🪝 Hooks 🧩 Components
🧪 Testing 🔍 Review 📋 Docs 🚀 Deploy
Metrics Visualization
Code Size Reduction
BEFORE AFTER
────────────────────────────
887 LOC ██████████████████│ GitHubActionsFetcher
│95 LOC ██ (89% ↓)
733 LOC ███████████████ │ NerdModeIDE
│110 LOC ██ (85% ↓)
686 LOC ███████████████ │ LuaEditor
│120 LOC ██ (82% ↓)
Component Count
BEFORE: 3 large components
AFTER: 25 small components
Distribution:
GitHub Features: 7 components
IDE Features: 8 components
Lua Features: 10 components
Average Size:
Before: 569 LOC
After: 73 LOC (87% reduction)
Custom Hooks Growth
BEFORE: 5 hooks
AFTER: 20+ hooks
By Feature:
GitHub: 3 hooks
IDE: 5 hooks
Lua: 4 hooks
Other: 8+ hooks
Testing Coverage
BEFORE: Limited component testing
AFTER: Comprehensive testing
Unit Tests: 50+ (hooks, utilities)
Component Tests: 20+ (each component)
Integration: 10+ (workflows)
E2E: 5+ (full features)
Coverage Target: 80%+
Risk Mitigation Map
RISKS MITIGATION
────────────────────────────────────────────
Database Migration → Backup before
(Data Loss) Run in staging
Test rollback
Hook API Breaking → Comprehensive
(Regressions) testing
Backward compat
Performance Degradation → Benchmarking
(Slow renders) Profiling
Optimization
Token Security Issues → Encryption
(Breach) Environment vars
No hardcoding
Scope Creep → Strict checklist
(Missed deadline) Weekly reviews
Limit changes
Team Capacity → Parallel work
(Over-commitment) Clear ownership
Time estimation
Success Criteria Checklist
CODE QUALITY │ ARCHITECTURE
├─ All files < 150 LOC ✓ ├─ Single responsibility ✓
├─ 80%+ test coverage ✓ ├─ Logic in hooks/Lua ✓
├─ No ESLint violations ✓ ├─ State in DB/React ✓
├─ No TypeScript errors ✓ ├─ Clean composition ✓
└─ Proper error handling ✓ └─ No prop drilling ✓
PERFORMANCE │ TESTING
├─ Render < 100ms ✓ ├─ All hooks tested ✓
├─ DB queries < 50ms ✓ ├─ All components tested ✓
├─ No memory leaks ✓ ├─ Integration tests ✓
├─ No unnecessary re-renders ✓ ├─ E2E tests passing ✓
└─ Minimal bundle impact ✓ └─ No regressions ✓
Documentation Structure
docs/
├── REFACTORING_INDEX.md (←You are here)
│ └─ Links to all resources
│
├── REFACTORING_SUMMARY.md
│ └─ Executive overview
│
├── REFACTORING_STRATEGY.md
│ └─ Detailed technical blueprint
│
├── REFACTORING_CHECKLIST.md
│ └─ Implementation tasks
│
└── REFACTORING_QUICK_REFERENCE.md
└─ Patterns & templates
Generated: December 25, 2025
Visual Summary Complete ✅
Ready for Implementation 🚀