Type: L3 Worker Category: 7XX Project Bootstrap Parent: ln-720-structure-migrator

Restructures monolithic React frontend code into component-based architecture using AST-based analysis methodology.

Purpose & Scope

| 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

Workflow

| 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

Phase 1: Analyze

Scan current frontend structure and classify components.

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

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

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

| 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

| 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

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

Definition of Done

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

| 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

| 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

ln-721-frontend-restructure

安装