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.

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

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.