451 lines
12 KiB
Markdown
451 lines
12 KiB
Markdown
# Investment Trading Monorepo Roadmap
|
|
|
|
## 1. Purpose
|
|
|
|
This roadmap turns the PRD into an execution plan 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
|
|
|
|
## 2. Guiding Rules
|
|
|
|
1. Build the target repo cleanly first.
|
|
2. Do not duplicate auth, kill switch, telemetry, or config bootstrap.
|
|
3. Do not move core trading moat into common-platform packages.
|
|
4. Do not preserve legacy repo boundaries inside the new monorepo if they block clarity.
|
|
5. Migrate by contract, not by uncontrolled file copying.
|
|
|
|
## 3. Target Repository Shape
|
|
|
|
```text
|
|
learning_ai_invt_trdg/
|
|
├── app/ or src/ # Expo mobile app
|
|
├── web/ # Web dashboard
|
|
├── backend/ # Trading backend
|
|
├── shared/
|
|
│ └── product.json
|
|
├── docs/
|
|
├── scripts/
|
|
├── pnpm-workspace.yaml
|
|
├── package.json
|
|
├── docker-compose.yml
|
|
└── .env.example
|
|
```
|
|
|
|
## 4. Workstreams
|
|
|
|
### 4.1 Product and architecture
|
|
|
|
- define canonical product identity
|
|
- define surface boundaries
|
|
- define backend authority model
|
|
- define migration/cutover plan
|
|
|
|
### 4.2 Shared platform integration
|
|
|
|
- auth
|
|
- kill switch
|
|
- feature flags
|
|
- telemetry
|
|
- diagnostics
|
|
- config and product metadata
|
|
|
|
### 4.3 Backend migration
|
|
|
|
- API and websocket contracts
|
|
- runtime control
|
|
- reconciliation and lifecycle
|
|
- observability
|
|
|
|
### 4.4 Web migration
|
|
|
|
- auth and session handling
|
|
- dashboard shell
|
|
- API/websocket client adaptation
|
|
- operator/admin workflows
|
|
|
|
### 4.5 Mobile rebuild
|
|
|
|
- auth bootstrap
|
|
- kill switch
|
|
- telemetry
|
|
- core monitor/intervention UX
|
|
|
|
### 4.6 Quality and release engineering
|
|
|
|
- scripts
|
|
- verification
|
|
- docs
|
|
- rollout readiness
|
|
|
|
## 5. Phase Plan
|
|
|
|
## Phase 0: Product Definition and Monorepo Foundation
|
|
|
|
### Objective
|
|
|
|
Create a credible target repository with clear product identity and explicit integration contracts before any code migration starts.
|
|
|
|
### Tasks
|
|
|
|
- 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
|
|
|
|
### Deliverables
|
|
|
|
- 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
|
|
|
|
## Phase 1: Shared Platform Contract Layer
|
|
|
|
### Objective
|
|
|
|
Ensure all surfaces adopt one consistent platform model for auth, kill switch, telemetry, flags, and diagnostics.
|
|
|
|
### Tasks
|
|
|
|
- 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
|
|
|
|
### Deliverables
|
|
|
|
- auth integration spec
|
|
- kill-switch behavior spec
|
|
- telemetry/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
|
|
|
|
## Phase 2: Backend First Migration
|
|
|
|
### Objective
|
|
|
|
Make backend the stable authority before web and mobile migrate heavily onto it.
|
|
|
|
### Why backend first
|
|
|
|
The trading product is safety-critical. Web and mobile must align around a stable backend authority model rather than dragging legacy assumptions forward.
|
|
|
|
### Tasks
|
|
|
|
- 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
|
|
|
|
### Keep local
|
|
|
|
- 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
|
|
|
|
### Exit Criteria
|
|
|
|
- backend has stable typed contracts
|
|
- auth is enforced consistently
|
|
- kill-switch and control semantics are defined and testable
|
|
|
|
## Phase 3: Web Dashboard Migration
|
|
|
|
### Objective
|
|
|
|
Move the web dashboard onto the new repo and onto shared platform bootstrap patterns.
|
|
|
|
### Tasks
|
|
|
|
- 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
|
|
|
|
### 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
|
|
|
|
### 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
|
|
|
|
## Phase 4: Mobile Rebuild
|
|
|
|
### Objective
|
|
|
|
Build mobile as a real ecosystem surface, not a mock UI shell.
|
|
|
|
### Tasks
|
|
|
|
- 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
|
|
|
|
### Mobile v1 scope recommendation
|
|
|
|
- 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
|
|
|
|
### Do not do in mobile v1
|
|
|
|
- full parity with advanced web configuration
|
|
- highly complex strategy editing
|
|
- 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
|
|
|
|
## Phase 5: Cross-Repo DRY Consolidation
|
|
|
|
### Objective
|
|
|
|
Remove duplicated implementation patterns exposed during migration.
|
|
|
|
### Tasks
|
|
|
|
- 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
|
|
|
|
### Guardrail
|
|
|
|
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
|
|
|
|
## Phase 6: Verification, Release Readiness, and Cutover
|
|
|
|
### Objective
|
|
|
|
Validate that the new monorepo is safer and more coherent than the legacy setup before full adoption.
|
|
|
|
### Tasks
|
|
|
|
- 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
|
|
|
|
### Exit Criteria
|
|
|
|
- new monorepo is production-ready for staged adoption
|
|
- rollback and cutover are documented
|
|
|
|
## 6. Detailed Work Breakdown
|
|
|
|
## 6.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
|
|
|
|
## 6.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
|
|
|
|
## 6.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
|
|
|
|
## 6.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
|
|
|
|
## 7. 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
|
|
|
|
## 8. 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
|
|
|
|
### 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
|
|
|
|
### Risk: kill switch becomes semantically overloaded
|
|
|
|
Mitigation:
|
|
|
|
- define separate concepts for:
|
|
- product maintenance mode
|
|
- product-level access disable
|
|
- trade-halt control
|
|
- profile-level disable
|
|
|
|
### Risk: mobile becomes a weak afterthought
|
|
|
|
Mitigation:
|
|
|
|
- scope it honestly as monitor/intervene-first
|
|
- wire full platform integration from day one
|
|
|
|
### Risk: over-extraction into common platform
|
|
|
|
Mitigation:
|
|
|
|
- keep trading logic local unless there is proven reuse
|
|
|
|
## 9. Decision Log
|
|
|
|
### Decision 1
|
|
|
|
Use a new monorepo instead of incremental retrofitting of three existing repos.
|
|
|
|
Reason:
|
|
|
|
- lower long-term complexity
|
|
- cleaner product identity
|
|
- fewer transitional glue layers
|
|
|
|
### Decision 2
|
|
|
|
Use `learning_ai_fastgap` as structural reference, not as a cloning template.
|
|
|
|
Reason:
|
|
|
|
- the surface layout pattern is proven
|
|
- the domain is different and must not inherit unrelated product assumptions
|
|
|
|
### Decision 3
|
|
|
|
Use `learning_ai_common_plat` as ecosystem backbone for generic platform concerns.
|
|
|
|
Reason:
|
|
|
|
- avoids duplicated auth, kill switch, telemetry, config, and diagnostics work
|
|
|
|
## 10. Acceptance Criteria for This Roadmap
|
|
|
|
This roadmap is successful if it can guide implementation without ambiguity on:
|
|
|
|
- repo structure
|
|
- product identity
|
|
- platform integration boundaries
|
|
- backend authority model
|
|
- migration sequence
|
|
- DRY extraction rules
|
|
- risk controls
|
|
|
|
## 11. Recommended Immediate Next Steps
|
|
|
|
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.
|