From 30551b876b8ea5d52dbf667d561cc6e9ea68409d Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 4 Apr 2026 02:32:17 -0700 Subject: [PATCH] docs: convert roadmap into execution tracker --- docs/ROADMAP.md | 726 ++++++++++++++++++++++++------------------------ 1 file changed, 356 insertions(+), 370 deletions(-) diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 6210ba1..414dc91 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -2,15 +2,29 @@ ## 1. Purpose -This roadmap turns the PRD into an execution plan for `learning_ai_invt_trdg`, the new canonical monorepo for the trading product. +This roadmap is the execution tracker for `learning_ai_invt_trdg`, the new canonical monorepo for the trading product. It assumes: - `learning_ai_fastgap` is the structural reference monorepo - `learning_ai_common_plat` is the shared ecosystem dependency source -- the three current trading repos are migration inputs, not the permanent architecture +- `bytelyst-trading-dashboard-web`, `bytelyst-trading-bot-service`, and `bytelyst-trading-dashboard-mob` are migration inputs, not the target architecture -## 2. Guiding Rules +## 2. Status Model + +### Overall status + +- Current phase: `Phase 0` +- Overall state: `Not Started` + +### Legend + +- `[ ]` not started +- `[-]` in progress +- `[x]` done +- `[!]` blocked / decision needed + +## 3. Guiding Rules 1. Build the target repo cleanly first. 2. Do not duplicate auth, kill switch, telemetry, or config bootstrap. @@ -18,17 +32,16 @@ It assumes: 4. Do not preserve legacy repo boundaries inside the new monorepo if they block clarity. 5. Migrate by contract, not by uncontrolled file copying. -### 2.1 Second-Pass Review Improvements +## 4. Critical Path -This revision tightens: +- [ ] Canonical product identity +- [ ] Shared platform contract +- [ ] Backend authority and contracts +- [ ] Web migration +- [ ] Mobile migration +- [ ] Verification and cutover -- system-of-record clarity -- migration mapping from legacy repos -- phase exit criteria -- cutover realism -- dependency visibility - -## 3. Target Repository Shape +## 5. Target Repository Shape ```text learning_ai_invt_trdg/ @@ -45,495 +58,461 @@ learning_ai_invt_trdg/ └── .env.example ``` -## 4. Workstreams +## 6. Dependency Matrix -### 4.1 Product and architecture +### Upstream dependencies -- define canonical product identity -- define surface boundaries -- define backend authority model -- define migration/cutover plan +- [ ] `learning_ai_common_plat` package compatibility confirmed +- [ ] platform-service auth behavior confirmed +- [ ] platform-service kill-switch behavior confirmed +- [ ] canonical product identity schema confirmed -### 4.2 Shared platform integration +### Internal dependencies -- auth -- kill switch -- feature flags -- telemetry -- diagnostics -- config and product metadata +- [ ] backend contracts available before web integration +- [ ] backend contracts available before mobile integration +- [ ] auth/session semantics finalized before surface wiring +- [ ] kill-switch semantics finalized before release readiness -### 4.3 Backend migration +## 7. Legacy Repo Migration Map -- API and websocket contracts -- runtime control -- reconciliation and lifecycle -- observability +### `bytelyst-trading-dashboard-web` -### 4.4 Web migration +- Destination: `web/` +- Rule: preserve valuable product UI and domain-facing client logic +- Rule: replace custom auth/bootstrap and duplicated platform plumbing -- auth and session handling -- dashboard shell -- API/websocket client adaptation -- operator/admin workflows +### `bytelyst-trading-bot-service` -### 4.5 Mobile rebuild +- Destination: `backend/` +- Rule: preserve domain and safety logic +- Rule: normalize config, auth boundaries, telemetry, and runtime control -- auth bootstrap -- kill switch -- telemetry -- core monitor/intervention UX +### `bytelyst-trading-dashboard-mob` -### 4.6 Quality and release engineering +- Destination: mobile `app/` or `src/` +- Rule: treat current mobile repo as design/input source, not final architecture -- scripts -- verification -- docs -- rollout readiness - -### 4.7 Migration and cutover management - -- legacy source inventory -- selective import strategy -- staged cutover plan -- rollback planning - -## 5. Phase Plan - -### 5.1 Critical Path - -The critical path is: - -- product identity -- shared platform contract -- backend authority -- web migration -- mobile migration -- verification and cutover +## 8. Phase Tracker ## Phase 0: Product Definition and Monorepo Foundation +### Status + +- State: `[ ] Not Started` +- Priority: `Critical` +- Depends on: none + ### Objective Create a credible target repository with clear product identity and explicit integration contracts before any code migration starts. -### Tasks +### Checklist -- create canonical product identity in `shared/product.json` -- define `package.json`, `pnpm-workspace.yaml`, and top-level scripts -- define root docs, local-dev model, and environment model -- define shared dependency strategy on `../learning_ai_common_plat/packages/*` -- define repo conventions based on FastGap where useful -- define product IDs, ports, env prefixes, domains, and package naming -- decide mobile root folder convention -- define root workspace naming conventions +- [ ] Create canonical product identity in `shared/product.json` +- [ ] Define root `package.json` +- [ ] Define `pnpm-workspace.yaml` +- [ ] Define top-level scripts +- [ ] Define root docs and local-dev model +- [ ] Define environment model and `.env.example` +- [ ] Define shared dependency strategy on `../learning_ai_common_plat/packages/*` +- [ ] Define repo conventions based on FastGap where useful +- [ ] Define product IDs, ports, env prefixes, domains, and package naming +- [ ] Decide mobile root folder convention +- [ ] Define root workspace naming conventions +- [ ] Define migration guardrails ### Deliverables -- root product metadata -- root package/workspace config -- initial repo skeleton -- environment contract -- migration design notes +- [ ] Root product metadata +- [ ] Root package/workspace config +- [ ] Initial repo skeleton +- [ ] Environment contract +- [ ] Migration design notes ### Exit Criteria -- repo structure is approved -- product identity is approved -- platform integration boundaries are approved -- migration guardrails are approved +- [ ] Repo structure approved +- [ ] Product identity approved +- [ ] Platform integration boundaries approved +- [ ] Migration guardrails approved ## Phase 1: Shared Platform Contract Layer +### Status + +- State: `[ ] Not Started` +- Priority: `Critical` +- Depends on: `Phase 0` + ### Objective -Ensure all surfaces adopt one consistent platform model for auth, kill switch, telemetry, flags, and diagnostics. +Ensure all surfaces adopt one consistent platform model for auth, kill switch, telemetry, flags, diagnostics, and config. -### Tasks +### Checklist -- define web auth pattern using `@bytelyst/react-auth` -- define mobile auth pattern using `@bytelyst/react-native-platform-sdk` -- define backend auth boundary and middleware strategy -- define kill-switch semantics across web, mobile, and backend -- define telemetry envelope fields -- define correlation ID and request propagation strategy -- define feature flag ownership and evaluation model -- define system-of-record ownership by concern -- define degraded-platform fallback behavior -- define transitional adapters needed for legacy auth flows +- [ ] Define web auth pattern using `@bytelyst/react-auth` +- [ ] Define mobile auth pattern using `@bytelyst/react-native-platform-sdk` +- [ ] Define backend auth boundary and middleware strategy +- [ ] Define kill-switch semantics across web, mobile, and backend +- [ ] Define ownership split between product accessibility controls and trading-behavior controls +- [ ] Define telemetry envelope fields +- [ ] Define correlation ID and request propagation strategy +- [ ] Define feature flag ownership and evaluation model +- [ ] Define system-of-record ownership by concern +- [ ] Define degraded-platform fallback behavior +- [ ] Define transitional adapters needed for legacy auth flows ### Deliverables -- auth integration spec -- kill-switch behavior spec -- telemetry/diagnostics contract -- shared config conventions +- [ ] Auth integration spec +- [ ] Kill-switch behavior spec +- [ ] Telemetry and diagnostics contract +- [ ] Shared config conventions ### Exit Criteria -- there is no ambiguity about platform-service versus product-backend responsibilities -- all three surfaces have approved integration patterns -- auth and kill-switch semantics are implementation-ready +- [ ] No ambiguity remains between platform-service and product-backend responsibilities +- [ ] All three surfaces have approved integration patterns +- [ ] Auth and kill-switch semantics are implementation-ready ## Phase 2: Backend First Migration +### Status + +- State: `[ ] Not Started` +- Priority: `Critical` +- Depends on: `Phase 1` + ### Objective Make backend the stable authority before web and mobile migrate heavily onto it. -### Why backend first +### Checklist -The trading product is safety-critical. Web and mobile must align around a stable backend authority model rather than dragging legacy assumptions forward. +- [ ] Create `backend/` workspace +- [ ] Define module layout under `backend/src` +- [ ] Classify legacy backend modules as keep, refactor, or drop +- [ ] Migrate core trading service modules selectively +- [ ] Split generic lib concerns from trading-domain modules +- [ ] Define typed API contracts for status, alerts, config, lifecycle, trade, admin control, and health +- [ ] Define websocket auth model and namespaces +- [ ] Define websocket scoping model +- [ ] Normalize config loading and schema validation +- [ ] Integrate platform-aware telemetry and diagnostics +- [ ] Integrate explicit kill-switch and maintenance semantics +- [ ] Assign backend enforcement for global trade halt, tenant disable, and profile disable +- [ ] Add runtime control endpoints +- [ ] Standardize admin controls and audit logging +- [ ] Define admin audit event schema +- [ ] Define durable state ownership between memory, database, and exchange sync +- [ ] Document deprecated endpoints and legacy compatibility strategy +- [ ] Add reconciliation and safety docs -### Tasks +### Keep Local -- create `backend/` workspace -- migrate core trading service modules selectively -- define typed API contract for status, alerts, config, lifecycle, trade, admin control, and health -- define websocket auth and scoping model -- normalize config loading and schema validation -- integrate platform-aware telemetry and diagnostics -- integrate explicit kill-switch and maintenance semantics -- standardize admin controls and audit logging -- document deprecated endpoints and legacy compatibility strategy -- classify legacy backend modules as keep, refactor, or drop -- define durable state ownership between memory, database, and exchange sync +- [ ] Trade execution +- [ ] Strategy logic +- [ ] Lifecycle and reconciliation +- [ ] Capital ledger +- [ ] Market and exchange integration -### Keep local +### Reuse from Common Platform -- trade execution -- strategy logic -- lifecycle and reconciliation -- capital ledger -- market/exchange integration - -### Reuse from common platform - -- auth middleware patterns -- config conventions -- telemetry infrastructure -- diagnostics patterns +- [ ] Auth middleware patterns +- [ ] Config conventions +- [ ] Telemetry infrastructure +- [ ] Diagnostics patterns ### Exit Criteria -- backend has stable typed contracts -- auth is enforced consistently -- kill-switch and control semantics are defined and testable -- backend is ready to anchor web and mobile integration +- [ ] Backend has stable typed contracts +- [ ] Auth is enforced consistently +- [ ] Kill-switch and control semantics are defined and testable +- [ ] Backend is ready to anchor web and mobile integration ## Phase 3: Web Dashboard Migration +### Status + +- State: `[ ] Not Started` +- Priority: `High` +- Depends on: `Phase 2` + ### Objective Move the web dashboard onto the new repo and onto shared platform bootstrap patterns. -### Tasks +### Checklist -- create `web/` workspace -- migrate UI modules by priority, not blindly -- replace custom auth provider with shared auth pattern -- move runtime config to common conventions -- standardize API client and websocket token propagation -- integrate maintenance and kill-switch UX states -- gate unfinished tabs/features behind flags -- define admin/operator routes and role-based controls -- normalize terminology, models, and UI behavior around backend authority -- classify each current web tab as ship, defer, or redesign -- remove legacy bootstrap duplication instead of porting it +- [ ] Create `web/` workspace +- [ ] Define app shell +- [ ] Replace custom auth provider with shared auth pattern +- [ ] Define route guards and role-aware rendering +- [ ] Move runtime config to common conventions +- [ ] Define product config +- [ ] Define API client and websocket client +- [ ] Standardize websocket token propagation +- [ ] Integrate maintenance and kill-switch UX states +- [ ] Define shell-level maintenance and kill-switch behavior +- [ ] Classify each current web tab as ship, defer, or redesign +- [ ] Migrate UI modules by priority, not blindly +- [ ] Gate unfinished tabs/features behind flags +- [ ] Define admin/operator routes and role-based controls +- [ ] Normalize terminology, models, and UI behavior around backend authority +- [ ] Remove legacy bootstrap duplication instead of porting it -### Priority order +### Priority Order -1. auth shell and session restore -2. overview, positions, history -3. config and settings -4. admin and runtime controls -5. advanced tabs such as marketplace and backtesting +- [ ] Auth shell and session restore +- [ ] Overview, positions, history +- [ ] Config and settings +- [ ] Admin and runtime controls +- [ ] Advanced tabs such as marketplace and backtesting ### Exit Criteria -- web is no longer dependent on legacy custom auth context -- web contracts align with new backend -- kill-switch and maintenance states are integrated -- web feels like one coherent product surface +- [ ] Web is no longer dependent on legacy custom auth context +- [ ] Web contracts align with new backend +- [ ] Kill-switch and maintenance states are integrated +- [ ] Web feels like one coherent product surface ## Phase 4: Mobile Rebuild +### Status + +- State: `[ ] Not Started` +- Priority: `High` +- Depends on: `Phase 2` + ### Objective Build mobile as a real ecosystem surface, not a mock UI shell. -### Tasks +### Checklist -- create Expo app structure following FastGap-style monorepo conventions -- add product config bootstrap -- integrate `@bytelyst/react-native-platform-sdk` -- implement auth flow and session restore -- implement launch-time kill-switch and maintenance handling -- add telemetry startup and error capture -- define initial mobile scope -- connect to backend and websocket/status contracts -- add push-notification-ready architecture -- define secure storage and session invalidation behavior -- define mobile action policy for monitor-first versus control-first flows +- [ ] Create Expo app structure following FastGap-style monorepo conventions +- [ ] Add product config bootstrap +- [ ] Integrate `@bytelyst/react-native-platform-sdk` +- [ ] Implement auth flow and session restore +- [ ] Define secure storage and session invalidation behavior +- [ ] Implement launch-time kill-switch and maintenance handling +- [ ] Add telemetry startup and error capture +- [ ] Define initial mobile scope +- [ ] Connect to backend and websocket/status contracts +- [ ] Add push-notification-ready architecture +- [ ] Define mobile action policy for monitor-first versus control-first flows +- [ ] Define alert and incident UX +- [ ] Define operator-safe interventions +- [ ] Define offline and degraded-state behavior -### Mobile v1 scope recommendation +### Mobile v1 Scope -- sign in / restore session -- portfolio overview -- alerts and critical incidents -- positions -- recent history -- settings and sign out -- safe operator controls limited to explicitly approved actions -- mobile is monitor-first, but not monitor-only +- [ ] Sign in / restore session +- [ ] Portfolio overview +- [ ] Alerts and critical incidents +- [ ] Positions +- [ ] Recent history +- [ ] Settings and sign out +- [ ] Safe operator controls limited to explicitly approved actions +- [ ] Maintain monitor-first, but not monitor-only scope -### Do not do in mobile v1 +### Do Not Do in Mobile v1 -- full parity with advanced web configuration -- highly complex strategy editing -- admin-only deep diagnostics UI unless clearly justified +- [ ] Do not pursue full parity with advanced web configuration +- [ ] Do not add highly complex strategy editing +- [ ] Do not add admin-only deep diagnostics UI unless clearly justified ### Exit Criteria -- mobile is integrated with platform auth and kill switch -- mobile consumes the same product contracts as web -- mobile scope is honest and operationally safe +- [ ] Mobile is integrated with platform auth and kill switch +- [ ] Mobile consumes the same product contracts as web +- [ ] Mobile scope is honest and operationally safe ## Phase 5: Cross-Repo DRY Consolidation +### Status + +- State: `[ ] Not Started` +- Priority: `Medium` +- Depends on: `Phases 2-4` + ### Objective Remove duplicated implementation patterns exposed during migration. -### Tasks +### Checklist -- consolidate auth/session bootstrap -- consolidate product config resolution -- consolidate request headers and token propagation helpers -- consolidate telemetry boot and event fields -- consolidate kill-switch UX and service-state handling -- consolidate shared types for product contracts -- remove temporary migration-only adapters that are no longer needed +- [ ] Consolidate auth/session bootstrap +- [ ] Consolidate product config resolution +- [ ] Consolidate request headers and token propagation helpers +- [ ] Consolidate telemetry boot and event fields +- [ ] Consolidate kill-switch UX and service-state handling +- [ ] Consolidate shared types for product contracts +- [ ] Remove temporary migration-only adapters that are no longer needed ### Guardrail -Only extract code reused by at least two surfaces or clearly generic across ByteLyst products. +- [ ] Only extract code reused by at least two surfaces or clearly generic across ByteLyst products ### Exit Criteria -- no duplicate platform bootstrap flows remain -- common code lives in the right place with clear ownership -- extracted code respects the generic-versus-domain ownership rule +- [ ] No duplicate platform bootstrap flows remain +- [ ] Common code lives in the right place with clear ownership +- [ ] Extracted code respects the generic-versus-domain ownership rule ## Phase 6: Verification, Release Readiness, and Cutover +### Status + +- State: `[ ] Not Started` +- Priority: `Critical` +- Depends on: `Phases 2-5` + ### Objective Validate that the new monorepo is safer and more coherent than the legacy setup before full adoption. -### Tasks +### Checklist -- add root verify scripts -- add backend contract tests -- add web auth and kill-switch smoke tests -- add mobile launch/auth/kill-switch smoke coverage -- add docs for local dev, CI, Docker, and fallback behaviors -- define cutover sequencing from legacy repos -- define rollback paths -- define a release go/no-go checklist -- define post-cutover monitoring checks +- [ ] Add root verify scripts +- [ ] Add backend contract tests +- [ ] Add web auth and kill-switch smoke tests +- [ ] Add mobile launch/auth/kill-switch smoke coverage +- [ ] Add docs for local dev, CI, Docker, and fallback behaviors +- [ ] Define cutover sequencing from legacy repos +- [ ] Define rollback paths +- [ ] Define release go/no-go checklist +- [ ] Define post-cutover monitoring checks ### Exit Criteria -- new monorepo is production-ready for staged adoption -- rollback and cutover are documented -- engineers and operators can run the new repo confidently +- [ ] New monorepo is production-ready for staged adoption +- [ ] Rollback and cutover are documented +- [ ] Engineers and operators can run the new repo confidently -## 6. Legacy Repo Migration Map +## 9. Detailed Work Breakdown -### `bytelyst-trading-dashboard-web` +## 9.1 Root / Repository Tasks -Destination: +- [ ] Create root `package.json` +- [ ] Create `pnpm-workspace.yaml` +- [ ] Create `.env.example` +- [ ] Create `shared/product.json` +- [ ] Create `scripts/verify.sh` or equivalent +- [ ] Create root README +- [ ] Create docker/dev orchestration model +- [ ] Define naming conventions and import boundaries -- `web/` application shell, components, hooks, and product-facing client logic +## 9.2 Backend Tasks -Rule: +- [ ] Define module layout under `backend/src` +- [ ] Split generic lib concerns from trading-domain modules +- [ ] Add typed request/response schemas +- [ ] Add websocket session/auth model +- [ ] Add websocket auth model and namespaces +- [ ] Add runtime control endpoints +- [ ] Add telemetry and health integration +- [ ] Add reconciliation and safety docs +- [ ] Define admin audit event schema -- preserve valuable product UI and domain-facing client logic -- replace custom auth/bootstrap and duplicated platform plumbing +## 9.3 Web Tasks -### `bytelyst-trading-bot-service` +- [ ] Define app shell +- [ ] Define auth bootstrap +- [ ] Define product config +- [ ] Define API client and websocket client +- [ ] Port prioritized UI modules +- [ ] Integrate admin/operator states and surface messaging +- [ ] Define shell-level maintenance and kill-switch behavior -Destination: +## 9.4 Mobile Tasks -- `backend/` modules, services, and trading-domain infrastructure +- [ ] Define Expo structure +- [ ] Define navigation shell +- [ ] Define auth bootstrap and secure storage +- [ ] Define status polling/live update strategy +- [ ] Define alert/incident UX +- [ ] Define operator-safe interventions +- [ ] Define offline and degraded-state behavior -Rule: +## 10. Sequencing Recommendations -- preserve domain and safety logic -- normalize config, auth boundaries, telemetry, and runtime control +### Recommended Commit Order -### `bytelyst-trading-dashboard-mob` +- [ ] Repo scaffold and product identity +- [ ] Backend skeleton and config/auth contracts +- [ ] Backend runtime control and health contracts +- [ ] Web shell and auth migration +- [ ] Web dashboard migration by tab priority +- [ ] Mobile bootstrap and auth +- [ ] Mobile overview/alerts/positions/history +- [ ] DRY cleanup +- [ ] Verification and cutover docs -Destination: +### Recommended Rollout Order -- root mobile app structure and mobile product components +- [ ] Backend internal validation +- [ ] Web internal adoption +- [ ] Mobile internal beta +- [ ] External / staged rollout -Rule: +## 11. Definition of Done by Phase -- treat current mobile repo as design/input source, not final architecture +- [ ] Docs are updated +- [ ] Contracts are explicit +- [ ] Verification has been run or the remaining gap is documented +- [ ] Ownership boundaries are clearer than before the phase started -## 7. Detailed Work Breakdown - -## 7.1 Root / repository tasks - -- create root `package.json` -- create `pnpm-workspace.yaml` -- create `.env.example` -- create `shared/product.json` -- create `scripts/verify.sh` or equivalent -- create root README -- create docker/dev orchestration model -- define naming conventions and import boundaries - -## 7.2 Backend tasks - -- define module layout under `backend/src` -- split generic lib concerns from trading-domain modules -- add typed request/response schemas -- add websocket session/auth model -- add runtime control endpoints -- add telemetry and health integration -- add reconciliation and safety docs -- define websocket auth model and namespaces -- define admin audit event schema - -## 7.3 Web tasks - -- define app shell -- define auth bootstrap -- define product config -- define API client and websocket client -- port prioritized UI modules -- integrate admin/operator states and surface messaging -- define shell-level maintenance and kill-switch behavior - -## 7.4 Mobile tasks - -- define Expo structure -- define navigation shell -- define auth bootstrap and secure storage -- define status polling/live update strategy -- define alert/incident UX -- define operator-safe interventions -- define offline and degraded-state behavior - -## 8. Dependency Matrix - -Upstream dependencies: - -- `learning_ai_common_plat` package compatibility -- platform-service auth and kill-switch behavior -- canonical product identity decision - -Internal dependencies: - -- backend contracts block web and mobile -- auth/session semantics block all surfaces -- kill-switch semantics block operator UX and release readiness - -## 9. Sequencing Recommendations - -### Recommended commit order at implementation time - -1. repo scaffold and product identity -2. backend skeleton and config/auth contracts -3. backend runtime control and health contracts -4. web shell and auth migration -5. web dashboard migration by tab priority -6. mobile bootstrap and auth -7. mobile overview/alerts/positions/history -8. DRY cleanup -9. verification and cutover docs - -### Recommended rollout order - -1. backend internal validation -2. web internal adoption -3. mobile internal beta -4. external/staged rollout - -## 10. Definition of Done by Phase - -Each phase is done only when: - -- docs are updated -- contracts are explicit -- verification has been run or the remaining gap is documented -- ownership boundaries are clearer than before the phase started - -## 11. Risks and Mitigations +## 12. Risks and Mitigations ### Risk: legacy assumptions leak into the new architecture -Mitigation: - -- define contracts first -- migrate by module and purpose -- reject dead or duplicate bootstrap code +- [ ] Mitigation: define contracts first +- [ ] Mitigation: migrate by module and purpose +- [ ] Mitigation: reject dead or duplicate bootstrap code ### Risk: auth model becomes split between Supabase-specific flows and platform-service flows -Mitigation: - -- use an adapter strategy during migration -- define one authoritative session model early -- document transitional behavior explicitly +- [ ] Mitigation: use an adapter strategy during migration +- [ ] Mitigation: define one authoritative session model early +- [ ] Mitigation: document transitional behavior explicitly ### Risk: kill switch becomes semantically overloaded -Mitigation: - -- define separate concepts for: -- product maintenance mode -- product-level access disable -- trade-halt control -- profile-level disable +- [ ] Mitigation: separate product maintenance mode from trade-halt control +- [ ] Mitigation: separate product-level access disable from profile-level disable ### Risk: mobile becomes a weak afterthought -Mitigation: - -- scope it honestly as monitor/intervene-first -- wire full platform integration from day one +- [ ] Mitigation: scope it honestly as monitor/intervene-first +- [ ] Mitigation: wire full platform integration from day one ### Risk: over-extraction into common platform -Mitigation: +- [ ] Mitigation: keep trading logic local unless there is proven reuse -- keep trading logic local unless there is proven reuse +## 13. Cutover Strategy -## 12. Cutover Strategy +### Recommended Cutover Approach -Recommended cutover approach: +- [ ] Build target contracts in the new repo +- [ ] Validate backend behavior in isolation +- [ ] Migrate internal web usage +- [ ] Release mobile in controlled beta +- [ ] Switch operational ownership only after monitoring and support confidence is established -1. build target contracts in the new repo -2. validate backend behavior in isolation -3. migrate internal web usage -4. release mobile in controlled beta -5. switch operational ownership only after monitoring and support confidence is established +### Avoid -Avoid: +- [ ] Big-bang replacement +- [ ] Silent endpoint swaps +- [ ] Prolonged dual-maintenance of business logic -- big-bang replacement -- silent endpoint swaps -- prolonged dual-maintenance of business logic - -## 13. Decision Log +## 14. Decision Log ### Decision 1 -Use a new monorepo instead of incremental retrofitting of three existing repos. +- [x] Use a new monorepo instead of incremental retrofitting of three existing repos Reason: @@ -543,7 +522,7 @@ Reason: ### Decision 2 -Use `learning_ai_fastgap` as structural reference, not as a cloning template. +- [x] Use `learning_ai_fastgap` as structural reference, not as a cloning template Reason: @@ -552,7 +531,7 @@ Reason: ### Decision 3 -Use `learning_ai_common_plat` as ecosystem backbone for generic platform concerns. +- [x] Use `learning_ai_common_plat` as ecosystem backbone for generic platform concerns Reason: @@ -560,7 +539,7 @@ Reason: ### Decision 4 -Treat mobile as monitor/intervene-first for initial scope. +- [x] Treat mobile as monitor/intervene-first for initial scope Reason: @@ -568,21 +547,28 @@ Reason: - reduces safety risk - avoids false parity with web -## 14. Acceptance Criteria for This Roadmap +### Decision 5 -This roadmap is successful if it can guide implementation without ambiguity on: +- [x] Assign product-level kill switch to platform-service and trading-behavior controls to the trading backend -- repo structure -- product identity -- platform integration boundaries -- backend authority model -- migration sequence -- DRY extraction rules -- risk controls +Reason: -## 15. Recommended Immediate Next Steps +- keeps trading enforcement with the backend authority +- avoids split ownership for safety-critical controls -1. Approve PRD and roadmap direction. -2. Scaffold the root monorepo structure. -3. Add `shared/product.json`, root `package.json`, `pnpm-workspace.yaml`, and `.env.example`. -4. Define backend contract skeleton before porting large amounts of legacy code. +## 15. Roadmap Acceptance Criteria + +- [ ] Repo structure is unambiguous +- [ ] Product identity is unambiguous +- [ ] Platform integration boundaries are unambiguous +- [ ] Backend authority model is unambiguous +- [ ] Migration sequence is unambiguous +- [ ] DRY extraction rules are unambiguous +- [ ] Risk controls are explicit + +## 16. Immediate Next Steps + +- [ ] Approve PRD and roadmap direction +- [ ] Scaffold the root monorepo structure +- [ ] Add `shared/product.json`, root `package.json`, `pnpm-workspace.yaml`, and `.env.example` +- [ ] Define backend contract skeleton before porting large amounts of legacy code