levnikolaevich/ln-721-frontend-restructure

Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

ln-721-frontend-restructure

Type: L3 Worker Category: 7XX Project Bootstrap

Frontend structure worker with two modes: SCAFFOLD (generate minimal React project from template) or RESTRUCTURE (migrate monolith to component-based architecture).

---

Mode Selection

| Mode | When | Input | Output | |------|------|-------|--------| | SCAFFOLD | CREATE pipeline — no existing frontend | Target stack config from ln-720 | Minimal React + Vite project (~7 files) | | RESTRUCTURE | TRANSFORM pipeline — existing frontend found | Monolithic React source | Component-based architecture |

---

Purpose & Scope

| Aspect | Description | |--------|-------------| | Input | Target stack config (SCAFFOLD) or monolithic React source (RESTRUCTURE) | | Output | Minimal project (SCAFFOLD) or component-based architecture (RESTRUCTURE) | | Framework | React + TypeScript + Vite |

Scope boundaries:

• SCAFFOLD: generates minimal starter files, no business logic
• RESTRUCTURE: restructures existing code, does not add new functionality
• Works with React + TypeScript projects
• Applies transformation rules from reference files

---

Workflow

SCAFFOLD Mode (CREATE pipeline)

| Phase | Name | Actions | Output | |-------|------|---------|--------| | S1 | Generate | Create minimal React + Vite + TypeScript project files | ~7 starter files | | S2 | Verify | Check file structure, validate configs | Valid project skeleton |

RESTRUCTURE Mode (TRANSFORM pipeline)

| Phase | Name | Actions | Output | |-------|------|---------|--------| | 1 | Analyze | Scan source, detect component types, measure complexity | File inventory, complexity metrics | | 2 | Plan | Apply split thresholds, calculate file moves, detect conflicts | Migration plan | | 3 | Execute | Create folders, extract content, update imports | Restructured files | | 4 | Verify | Run build, check imports, validate structure | Build success report |

---

SCAFFOLD Mode Phases

Phase S1: Generate Starter Files

Create minimal React + Vite + TypeScript project.

| File | Purpose | |------|---------| | package.json | Dependencies: react, react-dom, typescript, vite, @vitejs/plugin-react | | vite.config.ts | Vite config with React plugin, port, proxy settings | | tsconfig.json | Strict TypeScript config with path aliases | | index.html | Entry HTML with root div | | src/main.tsx | React entry point with StrictMode | | src/App.tsx | Root App component with router placeholder | | src/index.css | Base styles (reset, variables, layout) |

Phase S2: Verify Scaffold

| Check | Method | Expected | |-------|--------|----------| | All files created | File existence check | 7 files present | | package.json valid | JSON parse | No syntax errors | | tsconfig.json valid | JSON parse | No syntax errors | | No hardcoded values | Content scan | Project name from config, not hardcoded |

---

RESTRUCTURE Mode Phases

Phase 1: Analyze

Scan current frontend structure and classify components.

| Step | Action | Reference | |------|--------|-----------| | 1.1 | Scan all .tsx and .ts files in source | — | | 1.2 | Measure file complexity (lines, hooks, types) | transformation_rules.md | | 1.3 | Classify components by category | component_patterns.md | | 1.4 | Build import dependency graph | import_strategy.md |

Output: Component inventory with classifications and metrics.

---

Phase 2: Plan

Generate migration plan based on analysis.

| Step | Action | Reference | |------|--------|-----------| | 2.1 | Apply split thresholds to identify files to restructure | transformation_rules.md | | 2.2 | Calculate target paths for each file | react_folder_structure.md | | 2.3 | Identify import updates needed | import_strategy.md | | 2.4 | Detect potential conflicts (name collisions, circular deps) | — |

Output: Migration plan with Before/After mapping.

---

Phase 3: Execute

Apply transformations in correct order.

| Step | Action | Notes | |------|--------|-------| | 3.1 | Create directory structure | All target folders | | 3.2 | Extract types to types.ts | Types have no dependencies | | 3.3 | Extract constants to constants.ts | Constants depend only on types | | 3.4 | Extract hooks to hooks.ts | Hooks depend on types, constants | | 3.5 | Extract sub-components | Components use all above | | 3.6 | Create barrel exports (index.ts) | For clean imports | | 3.7 | Update all import paths | Fix references |

Order is critical: Execute in sequence to avoid broken imports.

---

Phase 4: Verify

Validate restructured project.

| Check | Command | Expected | |-------|---------|----------| | TypeScript compilation | npx tsc --noEmit | No errors | | Build | npm run build | Success | | No orphan files | Manual check | Source location empty | | Imports resolve | Build success | No module not found errors |

---

Transformation Summary

| Transformation | Before State | After State | |----------------|--------------|-------------| | Component Split | Single file >300 lines | Feature folder with co-located files | | Type Extraction | Inline interfaces | Separate types.ts | | Constant Extraction | Inline magic values | Separate constants.ts | | Hook Extraction | Inline useState/useEffect | Separate hooks.ts or shared hooks | | UI Component Move | Scattered in features | Centralized in components/ui/ | | Layout Component Move | Mixed with features | Centralized in components/layout/ |

---

Critical Rules

• Mode Awareness: SCAFFOLD creates from template; RESTRUCTURE transforms existing — never mix
• Single Responsibility: Handle only frontend structure, no backend changes
• Idempotent: Can re-run without duplicate files or corruption
• Build Verification: Must verify build passes after changes (RESTRUCTURE: npm run build)
• Preserve Functionality: No behavioral changes, only structural (RESTRUCTURE mode)
• Backup Strategy: Do not delete source files until verification passes (RESTRUCTURE mode)
• Import Consistency: Use path aliases for shared, relative for co-located

---

Definition of Done

SCAFFOLD mode:

• [ ] All 7 starter files generated
• [ ] package.json and tsconfig.json valid
• [ ] No hardcoded project names (uses config values)

RESTRUCTURE mode:

• [ ] All source files analyzed and classified
• [ ] Migration plan generated with Before/After mapping
• [ ] Directory structure created per template
• [ ] All extractions completed (types, constants, hooks, components)
• [ ] Import paths updated throughout project
• [ ] npm run build passes successfully
• [ ] No orphan imports or missing files
• [ ] Barrel exports created for shared folders

---

Risk Mitigation

| Risk | Detection | Mitigation | |------|-----------|------------| | Build failure after restructure | npm run build fails | Rollback: restore from source, investigate specific error | | Missing imports | Module not found errors | Scan all imports before/after, update missed paths | | Circular dependencies | Build warning or runtime error | Analyze dependency graph, break cycles by extracting shared code | | Lost functionality | Tests fail or UI broken | Run existing tests before/after transformation | | Name collisions | Duplicate export names | Rename with feature prefix before moving |

---

Reference Files

| File | Purpose | |------|---------| | references/transformation_rules.md | Split thresholds, extraction rules, transformation order | | references/component_patterns.md | Component classification by category | | references/import_strategy.md | Import update rules, path aliases, barrel exports | | references/react_folder_structure.md | Target directory structure template |

---

Version: 3.0.0 Last Updated: 2026-02-07