bytelyst/learning_ai_invt_trdg
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: convert roadmap into execution tracker

Browse Source
This commit is contained in:
Saravana Achu Mac 2026-04-04 02:32:17 -07:00
parent c747fe82fe
commit 30551b876b
1 changed files with 356 additions and 370 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

726
docs/ROADMAP.md
View File

@ -2,15 +2,29 @@
## 1. Purpose ## 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: It assumes:
- `learning_ai_fastgap` is the structural reference monorepo - `learning_ai_fastgap` is the structural reference monorepo
- `learning_ai_common_plat` is the shared ecosystem dependency source - `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. 1. Build the target repo cleanly first.
2. Do not duplicate auth, kill switch, telemetry, or config bootstrap. 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. 4. Do not preserve legacy repo boundaries inside the new monorepo if they block clarity.
5. Migrate by contract, not by uncontrolled file copying. 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 ## 5. Target Repository Shape
- migration mapping from legacy repos
- phase exit criteria
- cutover realism
- dependency visibility
## 3. Target Repository Shape
```text ```text
learning_ai_invt_trdg/ learning_ai_invt_trdg/
@ -45,495 +58,461 @@ learning_ai_invt_trdg/
└── .env.example └── .env.example
``` ```
## 4. Workstreams ## 6. Dependency Matrix
### 4.1 Product and architecture ### Upstream dependencies
- define canonical product identity - [ ] `learning_ai_common_plat` package compatibility confirmed
- define surface boundaries - [ ] platform-service auth behavior confirmed
- define backend authority model - [ ] platform-service kill-switch behavior confirmed
- define migration/cutover plan - [ ] canonical product identity schema confirmed
### 4.2 Shared platform integration ### Internal dependencies
- auth - [ ] backend contracts available before web integration
- kill switch - [ ] backend contracts available before mobile integration
- feature flags - [ ] auth/session semantics finalized before surface wiring
- telemetry - [ ] kill-switch semantics finalized before release readiness
- diagnostics
- config and product metadata
### 4.3 Backend migration ## 7. Legacy Repo Migration Map
- API and websocket contracts ### `bytelyst-trading-dashboard-web`
- runtime control
- reconciliation and lifecycle
- observability
### 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 ### `bytelyst-trading-bot-service`
- dashboard shell
- API/websocket client adaptation
- operator/admin workflows
### 4.5 Mobile rebuild - Destination: `backend/`
- Rule: preserve domain and safety logic
- Rule: normalize config, auth boundaries, telemetry, and runtime control
- auth bootstrap ### `bytelyst-trading-dashboard-mob`
- kill switch
- telemetry
- core monitor/intervention UX
### 4.6 Quality and release engineering - Destination: mobile `app/` or `src/`
- Rule: treat current mobile repo as design/input source, not final architecture
- scripts ## 8. Phase Tracker
- 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
## Phase 0: Product Definition and Monorepo Foundation ## Phase 0: Product Definition and Monorepo Foundation
### Status
- State: `[ ] Not Started`
- Priority: `Critical`
- Depends on: none
### Objective ### Objective
Create a credible target repository with clear product identity and explicit integration contracts before any code migration starts. 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` - [ ] Create canonical product identity in `shared/product.json`
- define `package.json`, `pnpm-workspace.yaml`, and top-level scripts - [ ] Define root `package.json`
- define root docs, local-dev model, and environment model - [ ] Define `pnpm-workspace.yaml`
- define shared dependency strategy on `../learning_ai_common_plat/packages/*` - [ ] Define top-level scripts
- define repo conventions based on FastGap where useful - [ ] Define root docs and local-dev model
- define product IDs, ports, env prefixes, domains, and package naming - [ ] Define environment model and `.env.example`
- decide mobile root folder convention - [ ] Define shared dependency strategy on `../learning_ai_common_plat/packages/*`
- define root workspace naming conventions - [ ] 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 ### Deliverables
- root product metadata - [ ] Root product metadata
- root package/workspace config - [ ] Root package/workspace config
- initial repo skeleton - [ ] Initial repo skeleton
- environment contract - [ ] Environment contract
- migration design notes - [ ] Migration design notes
### Exit Criteria ### Exit Criteria
- repo structure is approved - [ ] Repo structure approved
- product identity is approved - [ ] Product identity approved
- platform integration boundaries are approved - [ ] Platform integration boundaries approved
- migration guardrails are approved - [ ] Migration guardrails approved
## Phase 1: Shared Platform Contract Layer ## Phase 1: Shared Platform Contract Layer
### Status
- State: `[ ] Not Started`
- Priority: `Critical`
- Depends on: `Phase 0`
### Objective ### 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 web auth pattern using `@bytelyst/react-auth`
- define mobile auth pattern using `@bytelyst/react-native-platform-sdk` - [ ] Define mobile auth pattern using `@bytelyst/react-native-platform-sdk`
- define backend auth boundary and middleware strategy - [ ] Define backend auth boundary and middleware strategy
- define kill-switch semantics across web, mobile, and backend - [ ] Define kill-switch semantics across web, mobile, and backend
- define telemetry envelope fields - [ ] Define ownership split between product accessibility controls and trading-behavior controls
- define correlation ID and request propagation strategy - [ ] Define telemetry envelope fields
- define feature flag ownership and evaluation model - [ ] Define correlation ID and request propagation strategy
- define system-of-record ownership by concern - [ ] Define feature flag ownership and evaluation model
- define degraded-platform fallback behavior - [ ] Define system-of-record ownership by concern
- define transitional adapters needed for legacy auth flows - [ ] Define degraded-platform fallback behavior
- [ ] Define transitional adapters needed for legacy auth flows
### Deliverables ### Deliverables
- auth integration spec - [ ] Auth integration spec
- kill-switch behavior spec - [ ] Kill-switch behavior spec
- telemetry/diagnostics contract - [ ] Telemetry and diagnostics contract
- shared config conventions - [ ] Shared config conventions
### Exit Criteria ### Exit Criteria
- there is no ambiguity about platform-service versus product-backend responsibilities - [ ] No ambiguity remains between platform-service and product-backend responsibilities
- all three surfaces have approved integration patterns - [ ] All three surfaces have approved integration patterns
- auth and kill-switch semantics are implementation-ready - [ ] Auth and kill-switch semantics are implementation-ready
## Phase 2: Backend First Migration ## Phase 2: Backend First Migration
### Status
- State: `[ ] Not Started`
- Priority: `Critical`
- Depends on: `Phase 1`
### Objective ### Objective
Make backend the stable authority before web and mobile migrate heavily onto it. 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 - [ ] Trade execution
- migrate core trading service modules selectively - [ ] Strategy logic
- define typed API contract for status, alerts, config, lifecycle, trade, admin control, and health - [ ] Lifecycle and reconciliation
- define websocket auth and scoping model - [ ] Capital ledger
- normalize config loading and schema validation - [ ] Market and exchange integration
- 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
### Keep local ### Reuse from Common Platform
- trade execution - [ ] Auth middleware patterns
- strategy logic - [ ] Config conventions
- lifecycle and reconciliation - [ ] Telemetry infrastructure
- capital ledger - [ ] Diagnostics patterns
- market/exchange integration
### Reuse from common platform
- auth middleware patterns
- config conventions
- telemetry infrastructure
- diagnostics patterns
### Exit Criteria ### Exit Criteria
- backend has stable typed contracts - [ ] Backend has stable typed contracts
- auth is enforced consistently - [ ] Auth is enforced consistently
- kill-switch and control semantics are defined and testable - [ ] Kill-switch and control semantics are defined and testable
- backend is ready to anchor web and mobile integration - [ ] Backend is ready to anchor web and mobile integration
## Phase 3: Web Dashboard Migration ## Phase 3: Web Dashboard Migration
### Status
- State: `[ ] Not Started`
- Priority: `High`
- Depends on: `Phase 2`
### Objective ### Objective
Move the web dashboard onto the new repo and onto shared platform bootstrap patterns. Move the web dashboard onto the new repo and onto shared platform bootstrap patterns.
### Tasks ### Checklist
- create `web/` workspace - [ ] Create `web/` workspace
- migrate UI modules by priority, not blindly - [ ] Define app shell
- replace custom auth provider with shared auth pattern - [ ] Replace custom auth provider with shared auth pattern
- move runtime config to common conventions - [ ] Define route guards and role-aware rendering
- standardize API client and websocket token propagation - [ ] Move runtime config to common conventions
- integrate maintenance and kill-switch UX states - [ ] Define product config
- gate unfinished tabs/features behind flags - [ ] Define API client and websocket client
- define admin/operator routes and role-based controls - [ ] Standardize websocket token propagation
- normalize terminology, models, and UI behavior around backend authority - [ ] Integrate maintenance and kill-switch UX states
- classify each current web tab as ship, defer, or redesign - [ ] Define shell-level maintenance and kill-switch behavior
- remove legacy bootstrap duplication instead of porting it - [ ] 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 - [ ] Auth shell and session restore
2. overview, positions, history - [ ] Overview, positions, history
3. config and settings - [ ] Config and settings
4. admin and runtime controls - [ ] Admin and runtime controls
5. advanced tabs such as marketplace and backtesting - [ ] Advanced tabs such as marketplace and backtesting
### Exit Criteria ### Exit Criteria
- web is no longer dependent on legacy custom auth context - [ ] Web is no longer dependent on legacy custom auth context
- web contracts align with new backend - [ ] Web contracts align with new backend
- kill-switch and maintenance states are integrated - [ ] Kill-switch and maintenance states are integrated
- web feels like one coherent product surface - [ ] Web feels like one coherent product surface
## Phase 4: Mobile Rebuild ## Phase 4: Mobile Rebuild
### Status
- State: `[ ] Not Started`
- Priority: `High`
- Depends on: `Phase 2`
### Objective ### Objective
Build mobile as a real ecosystem surface, not a mock UI shell. Build mobile as a real ecosystem surface, not a mock UI shell.
### Tasks ### Checklist
- create Expo app structure following FastGap-style monorepo conventions - [ ] Create Expo app structure following FastGap-style monorepo conventions
- add product config bootstrap - [ ] Add product config bootstrap
- integrate `@bytelyst/react-native-platform-sdk` - [ ] Integrate `@bytelyst/react-native-platform-sdk`
- implement auth flow and session restore - [ ] Implement auth flow and session restore
- implement launch-time kill-switch and maintenance handling - [ ] Define secure storage and session invalidation behavior
- add telemetry startup and error capture - [ ] Implement launch-time kill-switch and maintenance handling
- define initial mobile scope - [ ] Add telemetry startup and error capture
- connect to backend and websocket/status contracts - [ ] Define initial mobile scope
- add push-notification-ready architecture - [ ] Connect to backend and websocket/status contracts
- define secure storage and session invalidation behavior - [ ] Add push-notification-ready architecture
- define mobile action policy for monitor-first versus control-first flows - [ ] 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 - [ ] Sign in / restore session
- portfolio overview - [ ] Portfolio overview
- alerts and critical incidents - [ ] Alerts and critical incidents
- positions - [ ] Positions
- recent history - [ ] Recent history
- settings and sign out - [ ] Settings and sign out
- safe operator controls limited to explicitly approved actions - [ ] Safe operator controls limited to explicitly approved actions
- mobile is monitor-first, but not monitor-only - [ ] 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 - [ ] Do not pursue full parity with advanced web configuration
- highly complex strategy editing - [ ] Do not add highly complex strategy editing
- admin-only deep diagnostics UI unless clearly justified - [ ] Do not add admin-only deep diagnostics UI unless clearly justified
### Exit Criteria ### Exit Criteria
- mobile is integrated with platform auth and kill switch - [ ] Mobile is integrated with platform auth and kill switch
- mobile consumes the same product contracts as web - [ ] Mobile consumes the same product contracts as web
- mobile scope is honest and operationally safe - [ ] Mobile scope is honest and operationally safe
## Phase 5: Cross-Repo DRY Consolidation ## Phase 5: Cross-Repo DRY Consolidation
### Status
- State: `[ ] Not Started`
- Priority: `Medium`
- Depends on: `Phases 2-4`
### Objective ### Objective
Remove duplicated implementation patterns exposed during migration. Remove duplicated implementation patterns exposed during migration.
### Tasks ### Checklist
- consolidate auth/session bootstrap - [ ] Consolidate auth/session bootstrap
- consolidate product config resolution - [ ] Consolidate product config resolution
- consolidate request headers and token propagation helpers - [ ] Consolidate request headers and token propagation helpers
- consolidate telemetry boot and event fields - [ ] Consolidate telemetry boot and event fields
- consolidate kill-switch UX and service-state handling - [ ] Consolidate kill-switch UX and service-state handling
- consolidate shared types for product contracts - [ ] Consolidate shared types for product contracts
- remove temporary migration-only adapters that are no longer needed - [ ] Remove temporary migration-only adapters that are no longer needed
### Guardrail ### 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 ### Exit Criteria
- no duplicate platform bootstrap flows remain - [ ] No duplicate platform bootstrap flows remain
- common code lives in the right place with clear ownership - [ ] Common code lives in the right place with clear ownership
- extracted code respects the generic-versus-domain ownership rule - [ ] Extracted code respects the generic-versus-domain ownership rule
## Phase 6: Verification, Release Readiness, and Cutover ## Phase 6: Verification, Release Readiness, and Cutover
### Status
- State: `[ ] Not Started`
- Priority: `Critical`
- Depends on: `Phases 2-5`
### Objective ### Objective
Validate that the new monorepo is safer and more coherent than the legacy setup before full adoption. Validate that the new monorepo is safer and more coherent than the legacy setup before full adoption.
### Tasks ### Checklist
- add root verify scripts - [ ] Add root verify scripts
- add backend contract tests - [ ] Add backend contract tests
- add web auth and kill-switch smoke tests - [ ] Add web auth and kill-switch smoke tests
- add mobile launch/auth/kill-switch smoke coverage - [ ] Add mobile launch/auth/kill-switch smoke coverage
- add docs for local dev, CI, Docker, and fallback behaviors - [ ] Add docs for local dev, CI, Docker, and fallback behaviors
- define cutover sequencing from legacy repos - [ ] Define cutover sequencing from legacy repos
- define rollback paths - [ ] Define rollback paths
- define a release go/no-go checklist - [ ] Define release go/no-go checklist
- define post-cutover monitoring checks - [ ] Define post-cutover monitoring checks
### Exit Criteria ### Exit Criteria
- new monorepo is production-ready for staged adoption - [ ] New monorepo is production-ready for staged adoption
- rollback and cutover are documented - [ ] Rollback and cutover are documented
- engineers and operators can run the new repo confidently - [ ] 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 ## 9.3 Web Tasks
- replace custom auth/bootstrap and duplicated platform plumbing
### `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 ### Recommended Commit Order
- normalize config, auth boundaries, telemetry, and runtime control
### `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 ## 12. Risks and Mitigations
## 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
### Risk: legacy assumptions leak into the new architecture ### Risk: legacy assumptions leak into the new architecture
Mitigation: - [ ] Mitigation: define contracts first
- [ ] Mitigation: migrate by module and purpose
- define contracts first - [ ] Mitigation: reject dead or duplicate bootstrap code
- migrate by module and purpose
- reject dead or duplicate bootstrap code
### Risk: auth model becomes split between Supabase-specific flows and platform-service flows ### Risk: auth model becomes split between Supabase-specific flows and platform-service flows
Mitigation: - [ ] Mitigation: use an adapter strategy during migration
- [ ] Mitigation: define one authoritative session model early
- use an adapter strategy during migration - [ ] Mitigation: document transitional behavior explicitly
- define one authoritative session model early
- document transitional behavior explicitly
### Risk: kill switch becomes semantically overloaded ### Risk: kill switch becomes semantically overloaded
Mitigation: - [ ] Mitigation: separate product maintenance mode from trade-halt control
- [ ] Mitigation: separate product-level access disable from profile-level disable
- define separate concepts for:
- product maintenance mode
- product-level access disable
- trade-halt control
- profile-level disable
### Risk: mobile becomes a weak afterthought ### Risk: mobile becomes a weak afterthought
Mitigation: - [ ] Mitigation: scope it honestly as monitor/intervene-first
- [ ] Mitigation: wire full platform integration from day one
- scope it honestly as monitor/intervene-first
- wire full platform integration from day one
### Risk: over-extraction into common platform ### 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 ### Avoid
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: - [ ] Big-bang replacement
- [ ] Silent endpoint swaps
- [ ] Prolonged dual-maintenance of business logic
- big-bang replacement ## 14. Decision Log
- silent endpoint swaps
- prolonged dual-maintenance of business logic
## 13. Decision Log
### Decision 1 ### 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: Reason:
@ -543,7 +522,7 @@ Reason:
### Decision 2 ### 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: Reason:
@ -552,7 +531,7 @@ Reason:
### Decision 3 ### 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: Reason:
@ -560,7 +539,7 @@ Reason:
### Decision 4 ### Decision 4
Treat mobile as monitor/intervene-first for initial scope. - [x] Treat mobile as monitor/intervene-first for initial scope
Reason: Reason:
@ -568,21 +547,28 @@ Reason:
- reduces safety risk - reduces safety risk
- avoids false parity with web - 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 Reason:
- product identity
- platform integration boundaries
- backend authority model
- migration sequence
- DRY extraction rules
- risk controls
## 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. ## 15. Roadmap Acceptance Criteria
2. Scaffold the root monorepo structure.
3. Add `shared/product.json`, root `package.json`, `pnpm-workspace.yaml`, and `.env.example`. - [ ] Repo structure is unambiguous
4. Define backend contract skeleton before porting large amounts of legacy code. - [ ] 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