ln-721-frontend-restructure

| Aspect | Description |

|--------|-------------|

| Input | Monolithic React frontend source |

| Output | Component-based architecture with co-located feature folders |

| Framework | React only |

Scope boundaries:

• Restructures existing code, does not add new functionality
• Works with React + TypeScript projects
• Applies transformation rules from reference files

---

| 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 |

---

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.

---

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.

---

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.

---

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 | 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/ |

---

• Single Responsibility: Handle only frontend restructuring, no backend changes
• Idempotent: Can re-run without duplicate files or corruption
• Build Verification: Must verify npm run build passes after changes
• Preserve Functionality: No behavioral changes, only structural
• Backup Strategy: Do not delete source files until verification passes
• Import Consistency: Use path aliases for shared, relative for co-located

---

• [ ] 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 | 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 |

---

| 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: 2.0.0

Last Updated: 2026-01-10