You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: revise migration plan to inside-out strategy with vertical UI slices
Replace horizontal layer-by-layer migration (8 phases) with inside-out
approach (7 phases). New strategy hollows out old provider and controller
from the inside by delegating to new adapter and services, then migrates
UI as vertical slices per screen.
Key changes:
- Add compat/ translation layer for bidirectional type mapping
- Phase 2: Adapter replaces provider internals
- Phases 3-4: Services replace controller internals (parallelizable)
- Phase 5: New controller, old becomes pure shim
- Phase 6: UI migrates one screen at a time (vertical slices)
- Phase 7: Cleanup and rename (merged old phases 7+8)
Copy file name to clipboardExpand all lines: app/components/UI/PredictNext/README.md
+5-2Lines changed: 5 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -51,7 +51,10 @@ PredictNext/
51
51
│ └── phase-5-*.md
52
52
│ └── phase-6-*.md
53
53
│ └── phase-7-*.md
54
-
│ └── phase-8-*.md
54
+
├── compat/ # Temporary translation layer (deleted in Phase 7)
55
+
│ ├── mappers.ts
56
+
│ ├── types.ts
57
+
│ └── index.ts
55
58
├── types/
56
59
├── controller/
57
60
├── services/
@@ -120,4 +123,4 @@ Modules are deep with slim interfaces. We use compound components similar to the
120
123
121
124
## Migration Status
122
125
123
-
This feature is being built using a strangler fig migration from the original Predict directory. Check the [migration documentation](docs/migration/README.md) for details.
126
+
This feature is being built using an inside-out migration from the original Predict directory. The new adapter and services replace internals first while the old UI stays unchanged, then UI migrates as vertical slices. Check the [migration documentation](docs/migration/README.md) for details.
Copy file name to clipboardExpand all lines: app/components/UI/PredictNext/docs/migration/README.md
+87-57Lines changed: 87 additions & 57 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -27,22 +27,40 @@ The goal is not novelty. It is a codebase where a new team member can understand
27
27
28
28
## 2. Strategy
29
29
30
-
- Strangler fig migration: new code grows in `app/components/UI/PredictNext/`, old code shrinks in `app/components/UI/Predict/`.
31
-
- Bottom-up migration: data and orchestration move first, views move last.
32
-
- Every PR must be shippable, reviewable, and independently testable.
33
-
- External consumers make a clean cut with explicit import switches when a new module is ready.
34
-
- No shim, alias, or re-export layer between `Predict/` and `PredictNext/`.
30
+
Inside-out migration: replace the internals while keeping the external interface unchanged, then replace the interface once the internals are proven.
31
+
32
+
-**Bottom-up through the stack.** The new adapter grows first. The old PolymarketProvider progressively delegates API calls to it. Then new services grow, and the old PredictController progressively delegates to them. By the time UI migration starts, the entire data stack is battle-tested with real production traffic.
33
+
-**Translation layer as the seam.** A `compat/` module in PredictNext handles bidirectional mapping between canonical types (`PredictEvent`, `PredictMarket`, `PredictOutcome`) and legacy types (`Market`, `Outcome`, `OutcomeToken`). The data shapes are structurally identical — only the naming differs. Old code delegates down to new code, new code returns canonical types, the translation layer renames fields back to old shapes for old consumers.
34
+
-**Zero UI disruption during data migration.** Phases 2 through 5 touch only the data stack. Old hooks, components, and views continue working unchanged because the old controller's public interface and state shape remain stable throughout.
35
+
-**Vertical UI slices after data is proven.** Phase 6 replaces UI one screen at a time. Each slice includes new hooks, new components, and a new view for that screen. By then, the entire data layer is already in production.
36
+
-**Every PR is shippable.** Users see zero behavior change during Phases 1 through 5. UI changes appear gradually during Phase 6 as screens switch one by one.
37
+
-**No shim or re-export layer.** Old code delegates directly to new code via imports. New code never imports old code. The translation layer is the only bridge, and it gets deleted in Phase 7.
38
+
39
+
### How it works at each level
40
+
41
+
```
42
+
Phase 2 — Adapter replaces provider internals:
43
+
Old Provider method → calls New Adapter → gets canonical types → translates back to old types → returns
- small pure utilities under `app/components/UI/Predict/utils/`
45
-
- External consumers outside the Predict feature should switch explicitly once the relevant `PredictNext/` screen or component is ready. The main switch points are expected to include:
59
+
- Old code in `app/components/UI/Predict/` progressively delegates to PredictNext internals rather than being replaced all at once.
60
+
- A `PredictNext/compat/` module provides bidirectional type mappers between canonical and legacy types. This module is intentionally temporary and will be deleted in Phase 7.
61
+
- During the data migration (Phases 2 through 5), old UI code is completely untouched. Old hooks subscribe to the same old controller messenger events, receive the same old state shapes, and render the same old components.
62
+
- During the UI migration (Phase 6), each screen is rebuilt as a vertical slice using new hooks, components, and views that talk directly to the new controller. No screen ever mixes old and new hooks.
63
+
- External consumers outside the Predict feature switch imports during Phase 6 as each screen or widget becomes available in PredictNext. The main switch points are expected to include:
Note: Phases 2-3 and Phase 6 can run in parallel because service extraction depends on the canonical domain model, while component construction only needs the new types and ubiquitous language.
97
+
Note: Phases 3 and 4 can run in parallel because read services and write services are independent. Both depend on the adapter from Phase 2.
- Phase 3 extracts write and live-update services.
91
-
- Phase 4 composes those services behind a new controller.
92
-
- Phase 5 gives views a stable React interface.
106
+
- Phase 2 builds the adapter and hollows out the old provider.
107
+
- Phase 3 builds read services and hollows out the old controller's read methods.
93
108
94
-
### Stream B: UI primitives and widgets
109
+
### Stream B: Write path
95
110
96
-
`Phase 1 -> Phase 6`
111
+
`Phase 1 → Phase 2 → Phase 4`
97
112
98
-
- Phase 6 can start as soon as the `PredictEvent`, `PredictMarket`, `PredictOutcome`, `PredictPosition`, and `ActivityItem` types are stable.
99
-
-This stream should use mock data shaped from `PredictNext/types/index.ts`, not direct reads from controller state.
113
+
- Phase 4 can start as soon as the adapter from Phase 2 is stable.
114
+
-Write services (trading, transactions, live data, analytics) are independent of read services.
100
115
101
116
### Merge point
102
117
103
-
`Phase 7`
118
+
`Phase 5`
119
+
120
+
- The new controller composes all six services from both streams.
121
+
- The old controller becomes a pure translation shim.
122
+
123
+
### UI stream
104
124
105
-
- Views need both the new hooks from Stream A and the new primitives/widgets from Stream B.
125
+
`Phase 5 → Phase 6`
126
+
127
+
- UI migration starts only after the full data stack is proven in production.
128
+
- Within Phase 6, different screens can be migrated in parallel by different developers.
106
129
107
130
### Final stream
108
131
109
-
`Phase 8`
132
+
`Phase 7`
110
133
111
-
- Cleanup only starts after every routed screen and every external embed point has switched to `PredictNext/`.
134
+
- Cleanup starts after every routed screen and every external embed point has switched to PredictNext.
112
135
113
136
## 6. Risk Mitigation
114
137
115
-
-Each phase has explicit acceptance criteria and should not proceed on partial completion.
116
-
-Old code remains functional throughout the migration; revertability is preserved until the final rename.
117
-
-`PredictNext/` may delegate to old provider/controller logic early in the migration to reduce blast radius.
118
-
-Route-by-route migration prevents a big-bang UI rewrite.
119
-
- Feature flags can gate new `PredictNext/views/*` route registration if rollout needs to be staged.
120
-
-Rollback strategy is simple for Phases 1-7: revert `PredictNext/` PRs and keep old `Predict/` active.
121
-
-Service extraction should favor adapter seams and deterministic unit tests before production route switches.
138
+
-**Zero UI disruption during data migration.** Phases 2 through 5 do not touch any view, hook, or component file in old code. If a service extraction causes a regression, the failure is isolated to the data path and the old code can stop delegating with a one-line revert.
139
+
-**Translation layer is structurally trivial.** The canonical types and legacy types are isomorphic — same nesting, different names. The translation layer is field renames, not structural transformation, so the risk of data loss is minimal.
140
+
-**Incremental provider delegation.** Each adapter method is wired one at a time in the old provider. If one method causes issues, only that method reverts. The rest of the provider continues delegating.
141
+
-**Incremental controller delegation.** Same pattern: each controller method delegates to new services one at a time. Partial delegation is a stable intermediate state.
142
+
-**Feature work goes in old code.** During Phases 2 through 5, all new features are built in old Predict code. They automatically benefit from new internals because the old code delegates underneath. No confusion about where new code goes.
143
+
-**UI migration is per-screen.** Phase 6 migrates one screen at a time. Each screen switch is independently revertable. If the event details screen has issues, the event feed screen is unaffected.
144
+
-**Rollback at any phase.** Phases 1 through 5: stop delegating and revert PredictNext PRs. Phase 6: revert route switch for the affected screen. Phase 7: do not start until all screens are stable.
122
145
123
146
## 7. Definition of Done
124
147
@@ -127,6 +150,7 @@ Note: Phases 2-3 and Phase 6 can run in parallel because service extraction depe
127
150
- All component view tests for Predict pass against the migrated views.
128
151
- Engine registration points instantiate the new Predict controller.
129
152
- No runtime imports from old `Predict/` remain.
153
+
- Translation layer (`PredictNext/compat/`) is deleted.
130
154
-`UBIQUITOUS_LANGUAGE.md` is complete and reflected in code symbols.
131
155
-`PredictNext/README.md` and `PredictNext/docs/*` describe the shipped architecture rather than the transitional one.
132
156
@@ -140,7 +164,7 @@ The migration is not a file move only; it also corrects the domain model:
140
164
|`Outcome`|`Market`| Old outcome collections frequently map to binary markets |
141
165
|`OutcomeToken`|`Outcome`| Tradeable yes/no token becomes the new outcome concept |
142
166
143
-
These conversions must be applied consistently in:
167
+
These conversions are handled by the `PredictNext/compat/` translation layer during Phases 2 through 5. They must be applied consistently in:
144
168
145
169
-`PredictNext/types/index.ts`
146
170
- service method names
@@ -152,19 +176,25 @@ These conversions must be applied consistently in:
152
176
153
177
## 9. Recommended PR Order
154
178
155
-
1. Phase 1 contracts and error model
156
-
2. Phase 2 read/data services + registration
157
-
3. Phase 3 imperative services
158
-
4. Phase 4 thin controller + Engine switch
159
-
5. Phase 5 new hooks and hook consumers behind non-routed test surfaces
160
-
6. Phase 6 primitives/widgets in parallel
161
-
7. Phase 7 screen-by-screen route and consumer switches
162
-
8. Phase 8 deletion, rename, and final import cleanup
179
+
1. Phase 1 contracts, error model, and translation layer
180
+
2. Phase 2 adapter implementation and initial provider delegation
181
+
3. Phase 2 continued provider delegation (method by method, as many PRs as needed)
182
+
4. Phase 3 read services plus old controller read delegation
183
+
5. Phase 4 write services plus old controller write delegation (can parallel with 4)
184
+
6. Phase 5 new controller plus old controller becomes shim
0 commit comments