learning_ai_invt_trdg/docs/ROADMAP.md

Investment Trading Monorepo Roadmap

1. Purpose

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
• bytelyst-trading-dashboard-web, bytelyst-trading-bot-service, and bytelyst-trading-dashboard-mob are code-reference inputs, not the target architecture
• learning_ai_invt_trdg is a greenfield deployment with Cosmos DB as the only supported target persistence system

2. Status Model

Overall status

• Current phase: Phase 6
• Overall state: In Progress

Legend

• [ ] not started
• [-] in progress
• [x] done
• [!] blocked / decision needed

Implementation snapshot as of 2026-04-04

• Monorepo foundation scaffolded with root workspace config, shared runtime, shared product identity, local package linking, and verification scripts
• Backend migrated into backend/ and passing typecheck, build, test, and backend verification gates
• Web migrated into web/ with shared runtime, shared kill-switch gate, shared telemetry bootstrap, normalized backend URL resolution, and common-platform-native session handling
• Mobile migrated into mobile/ with product identity, shared runtime bootstrap, launch-time kill-switch gate, platform-service auth, live backend polling plus websocket-backed updates, startup/error telemetry capture, secure session storage with invalidation handling, and explicit degraded/offline status surfacing
• Backend now accepts common-platform JWTs and persists global trading-control state through Cosmos-backed control storage
• Dynamic config now flows through backend control-plane APIs with Cosmos-backed storage
• Backend snapshots now use a Cosmos-backed repository
• Distributed entry and reconciliation locks now use a Cosmos-backed repository
• Capital ledger persistence now uses a Cosmos-backed repository
• Mobile platform auth requests now use the common React Native platform SDK
• Backend risk and PnL aggregate reads now flow through repository abstractions instead of direct legacy service calls
• Web history, profile, marketplace, config, and manual-entry flows now run through backend APIs instead of browser-side table access
• Release smoke coverage now exists for web auth and product accessibility flows, with a tracked mobile release smoke checklist in operations
• Request ID propagation is now standardized across the main web/mobile API paths and echoed by backend HTTP responses
• Backtest feature access now reads from an explicit backend feature-flags contract instead of scraping generic runtime config
• Trading user profiles and marketplace presets now have Cosmos-backed authority paths
• Runtime order, trade-history, manual-entry, order-activity, and reconciliation-audit repositories now use Cosmos-backed trading-record storage instead of the legacy service layer
• Runtime sub-tag repair now operates through the Cosmos-backed order repository
• Root verification and lint flows now run successfully without sandbox-hostile script harness behavior
• [-] DRY cleanup completed for runtime/config/bootstrap concerns, shared websocket auth helpers, platform-session handling, and request tracing, but not yet for all persistence and feature-flag concerns
• [-] Cosmos-only execution persistence is now in place for the main backend runtime paths; remaining cleanup is removing dormant legacy code paths and reference scripts

3. 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. Rebuild by contract, not by uncontrolled file copying.
6. Do not preserve migration-only fallback behavior in the new runtime.

4. Critical Path

• Canonical product identity
• Shared platform contract
• Backend authority and contracts
• Web migration
• Mobile migration
• [-] Verification and cutover

5. Target Repository Shape

learning_ai_invt_trdg/
├── mobile/                     # Expo mobile app
├── web/                        # Web dashboard
├── backend/                    # Trading backend
├── shared/
│   └── product.json
├── docs/
├── scripts/
├── pnpm-workspace.yaml
├── package.json
├── docker-compose.yml
└── .env.example

6. Dependency Matrix

Upstream dependencies

• learning_ai_common_plat package compatibility confirmed
• platform-service auth behavior confirmed
• platform-service kill-switch behavior confirmed
• canonical product identity schema confirmed

Internal dependencies

• 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

7. Legacy Repo Migration Map

bytelyst-trading-dashboard-web

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

bytelyst-trading-bot-service

• Destination: backend/
• Rule: preserve domain and safety logic
• Rule: normalize config, auth boundaries, telemetry, and runtime control

bytelyst-trading-dashboard-mob

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

8. Phase Tracker

Phase 0: Product Definition and Monorepo Foundation

Status

• State: [x] Done
• Priority: Critical
• Depends on: none

Objective

Create a credible target repository with clear product identity and explicit integration contracts before any code migration starts.

Checklist

• 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 local common-platform package links
• 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

Exit Criteria

• Repo structure approved
• Product identity approved
• Platform integration boundaries approved
• Migration guardrails approved

Phase 1: Shared Platform Contract Layer

Status

• State: [x] Done
• Priority: Critical
• Depends on: Phase 0

Objective

Ensure all surfaces adopt one consistent platform model for auth, kill switch, telemetry, flags, diagnostics, and config.

Checklist

• Define web auth pattern using @bytelyst/react-auth
• Define mobile auth pattern using shared platform-service session contracts
• 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 behavior
• Define compatibility boundaries only where required to preserve domain behavior during derivation

Deliverables

• Auth integration spec
• Kill-switch behavior spec
• Telemetry and diagnostics contract
• Shared config conventions

Exit Criteria

• 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: [x] Done
• Priority: Critical
• Depends on: Phase 1

Objective

Make backend the stable authority before web and mobile migrate heavily onto it.

Checklist

• 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
• Add platform-JWT verification
• Add Cosmos-backed global trading-control persistence
• Move snapshots to Cosmos-backed repository flow
• Move distributed runtime locks to Cosmos-backed repository flow
• Move capital ledger persistence to Cosmos-backed repository flow
• [-] 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

Keep Local

• Trade execution
• Strategy logic
• Lifecycle and reconciliation
• Capital ledger
• Market and 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

Status

• State: [x] Done
• Priority: High
• Depends on: Phase 2

Objective

Move the web dashboard onto the new repo and onto shared platform bootstrap patterns.

Checklist

• Create web/ workspace
• Define app shell
• Replace custom auth provider with shared auth pattern
• Move public auth boundary to common-platform-native session handling
• 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

• 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

Phase 4: Mobile Rebuild

Status

• State: [x] Done
• Priority: High
• Depends on: Phase 2

Objective

Build mobile as a real ecosystem surface, not a mock UI shell.

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

• Sign in / restore session
• Portfolio overview
• Alerts and critical incidents
• Positions
• Recent history
• Settings and sign out
• Live state refresh via websocket with polling fallback
• [-] Safe operator controls limited to explicitly approved actions
• Maintain monitor-first, but not monitor-only scope

Do Not Do in Mobile v1

• 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

Phase 5: Cross-Repo DRY Consolidation

Status

• State: [-] In Progress
• Priority: Medium
• Depends on: Phases 2-4

Objective

Remove duplicated implementation patterns exposed during derivation from the legacy repos.

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 derivation-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

Status

• State: [-] In Progress
• 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.

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 degraded-platform 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

9. Detailed Work Breakdown

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

9.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 websocket auth model and namespaces
• Add runtime control endpoints
• Add telemetry and health integration
• Add Cosmos-first repository layer for snapshots, distributed locks, and capital ledger persistence
• Add reconciliation and safety docs
• Define admin audit event schema

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

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

10. Sequencing Recommendations

Recommended Commit Order

• 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
• Backend Cosmos-authoritative repository implementation for safety-critical persistence

Recommended Rollout Order

• Backend internal validation
• Web internal adoption
• Mobile internal beta
• External / staged rollout

11. Definition of Done by Phase

• 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

12. Risks and Mitigations

Risk: legacy assumptions leak into the new architecture

• Mitigation: define contracts first
• Mitigation: migrate by module and purpose
• Mitigation: reject dead or duplicate bootstrap code

Risk: auth model remains split between compatibility layers and the target platform-service session contract

• Mitigation: preserve domain behavior while removing migration-only storage fallbacks
• Mitigation: define one authoritative session model early
• Mitigation: document transitional behavior explicitly

Risk: repo-level verification stays red due to test-harness drift instead of product regressions

• Mitigation: keep backend safety gates green while cutting over persistence
• Mitigation: fix the web Vitest window.localStorage harness issue and keep root pnpm verify green while API contracts evolve

Risk: kill switch becomes semantically overloaded

• 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
• Mitigation: wire full platform integration from day one

Risk: over-extraction into common platform

• Mitigation: keep trading logic local unless there is proven reuse

13. Cutover Strategy

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

Avoid

• Big-bang replacement
• Silent endpoint swaps
• Prolonged dual-maintenance of business logic

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

Decision 5

• Assign product-level kill switch to platform-service and trading-behavior controls to the trading backend

Reason:

• keeps trading enforcement with the backend authority
• avoids split ownership for safety-critical controls

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

• Finish profile risk/PnL aggregate repository migration off legacy Supabase
• Finish remaining web direct legacy data-table reads and writes behind backend APIs
• Replace remaining transitional web auth compatibility surfaces with fully common-platform-native session handling
• Add release smoke coverage for web auth/kill-switch and mobile auth/kill-switch flows