learning_ai_invt_trdg/docs/ROADMAP.md

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.

2.1 Second-Pass Review Improvements

This revision tightens:

• system-of-record clarity
• migration mapping from legacy repos
• phase exit criteria
• cutover realism
• dependency visibility

3. Target Repository Shape

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

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

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
• decide mobile root folder convention
• define root workspace naming conventions

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
• migration guardrails 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
• 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

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

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
• classify legacy backend modules as keep, refactor, or drop
• define durable state ownership between memory, database, and exchange sync

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
• backend is ready to anchor web and mobile integration

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
• classify each current web tab as ship, defer, or redesign
• remove legacy bootstrap duplication instead of porting it

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
• web feels like one coherent product surface

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
• define secure storage and session invalidation behavior
• define mobile action policy for monitor-first versus control-first flows

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
• mobile is monitor-first, but not monitor-only

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
• mobile scope is honest and operationally safe

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
• 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.

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

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
• define a 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

6. Legacy Repo Migration Map

bytelyst-trading-dashboard-web

Destination:

• web/ application shell, components, hooks, and product-facing client logic

Rule:

• preserve valuable product UI and domain-facing client logic
• replace custom auth/bootstrap and duplicated platform plumbing

bytelyst-trading-bot-service

Destination:

• backend/ modules, services, and trading-domain infrastructure

Rule:

• preserve domain and safety logic
• normalize config, auth boundaries, telemetry, and runtime control

bytelyst-trading-dashboard-mob

Destination:

• root mobile app structure and mobile product components

Rule:

• treat current mobile repo as design/input source, not final architecture

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

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

12. Cutover Strategy

Recommended cutover approach:

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:

• big-bang replacement
• silent endpoint swaps
• prolonged dual-maintenance of business logic

13. 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

Decision 4

Treat mobile as monitor/intervene-first for initial scope.

Reason:

• improves delivery realism
• reduces safety risk
• avoids false parity with web

14. 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

15. 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.