ln-721-frontend-restructure
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
| 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
Workflow
| 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 |
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
- 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
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: 2.0.0
Last Updated: 2026-01-10
1---2name: ln-721-frontend-restructure3description: Restructures React frontend from monolith to component-based architecture4---5
6# ln-721-frontend-restructure
7
8**Type:** L3 Worker
9**Category:** 7XX Project Bootstrap
10**Parent:** ln-720-structure-migrator
11
12Restructures monolithic React frontend code into component-based architecture using AST-based analysis methodology.
13
14---
15
16## Purpose & Scope
17
18| Aspect | Description |
19|--------|-------------|
20| **Input** | Monolithic React frontend source |
21| **Output** | Component-based architecture with co-located feature folders |
22| **Framework** | React only |
23
24**Scope boundaries:**
25- Restructures existing code, does not add new functionality
26- Works with React + TypeScript projects
27- Applies transformation rules from reference files
28
29---
30
31## Workflow
32
33| Phase | Name | Actions | Output |
34|-------|------|---------|--------|
35| 1 | Analyze | Scan source, detect component types, measure complexity | File inventory, complexity metrics |
36| 2 | Plan | Apply split thresholds, calculate file moves, detect conflicts | Migration plan |
37| 3 | Execute | Create folders, extract content, update imports | Restructured files |
38| 4 | Verify | Run build, check imports, validate structure | Build success report |
39
40---
41
42## Phase 1: Analyze
43
44Scan current frontend structure and classify components.
45
46| Step | Action | Reference |
47|------|--------|-----------|
48| 1.1 | Scan all `.tsx` and `.ts` files in source | — |
49| 1.2 | Measure file complexity (lines, hooks, types) | `transformation_rules.md` |
50| 1.3 | Classify components by category | `component_patterns.md` |
51| 1.4 | Build import dependency graph | `import_strategy.md` |
52
53**Output:** Component inventory with classifications and metrics.
54
55---
56
57## Phase 2: Plan
58
59Generate migration plan based on analysis.
60
61| Step | Action | Reference |
62|------|--------|-----------|
63| 2.1 | Apply split thresholds to identify files to restructure | `transformation_rules.md` |
64| 2.2 | Calculate target paths for each file | `react_folder_structure.md` |
65| 2.3 | Identify import updates needed | `import_strategy.md` |
66| 2.4 | Detect potential conflicts (name collisions, circular deps) | — |
67
68**Output:** Migration plan with Before/After mapping.
69
70---
71
72## Phase 3: Execute
73
74Apply transformations in correct order.
75
76| Step | Action | Notes |
77|------|--------|-------|
78| 3.1 | Create directory structure | All target folders |
79| 3.2 | Extract types to `types.ts` | Types have no dependencies |
80| 3.3 | Extract constants to `constants.ts` | Constants depend only on types |
81| 3.4 | Extract hooks to `hooks.ts` | Hooks depend on types, constants |
82| 3.5 | Extract sub-components | Components use all above |
83| 3.6 | Create barrel exports (`index.ts`) | For clean imports |
84| 3.7 | Update all import paths | Fix references |
85
86**Order is critical:** Execute in sequence to avoid broken imports.
87
88---
89
90## Phase 4: Verify
91
92Validate restructured project.
93
94| Check | Command | Expected |
95|-------|---------|----------|
96| TypeScript compilation | `npx tsc --noEmit` | No errors |
97| Build | `npm run build` | Success |
98| No orphan files | Manual check | Source location empty |
99| Imports resolve | Build success | No module not found errors |
100
101---
102
103## Transformation Summary
104
105| Transformation | Before State | After State |
106|----------------|--------------|-------------|
107| Component Split | Single file >300 lines | Feature folder with co-located files |
108| Type Extraction | Inline interfaces | Separate `types.ts` |
109| Constant Extraction | Inline magic values | Separate `constants.ts` |
110| Hook Extraction | Inline useState/useEffect | Separate `hooks.ts` or shared hooks |
111| UI Component Move | Scattered in features | Centralized in `components/ui/` |
112| Layout Component Move | Mixed with features | Centralized in `components/layout/` |
113
114---
115
116## Critical Rules
117
118- **Single Responsibility:** Handle only frontend restructuring, no backend changes
119- **Idempotent:** Can re-run without duplicate files or corruption
120- **Build Verification:** Must verify `npm run build` passes after changes
121- **Preserve Functionality:** No behavioral changes, only structural
122- **Backup Strategy:** Do not delete source files until verification passes
123- **Import Consistency:** Use path aliases for shared, relative for co-located
124
125---
126
127## Definition of Done
128
129- [ ] All source files analyzed and classified
130- [ ] Migration plan generated with Before/After mapping
131- [ ] Directory structure created per template
132- [ ] All extractions completed (types, constants, hooks, components)
133- [ ] Import paths updated throughout project
134- [ ] `npm run build` passes successfully
135- [ ] No orphan imports or missing files
136- [ ] Barrel exports created for shared folders
137
138---
139
140## Risk Mitigation
141
142| Risk | Detection | Mitigation |
143|------|-----------|------------|
144| Build failure after restructure | `npm run build` fails | Rollback: restore from source, investigate specific error |
145| Missing imports | Module not found errors | Scan all imports before/after, update missed paths |
146| Circular dependencies | Build warning or runtime error | Analyze dependency graph, break cycles by extracting shared code |
147| Lost functionality | Tests fail or UI broken | Run existing tests before/after transformation |
148| Name collisions | Duplicate export names | Rename with feature prefix before moving |
149
150---
151
152## Reference Files
153
154| File | Purpose |
155|------|---------|
156| `references/transformation_rules.md` | Split thresholds, extraction rules, transformation order |
157| `references/component_patterns.md` | Component classification by category |
158| `references/import_strategy.md` | Import update rules, path aliases, barrel exports |
159| `references/react_folder_structure.md` | Target directory structure template |
160
161---
162
163**Version:** 2.0.0
164**Last Updated:** 2026-01-10
majiayu000