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 migration inputs, not the target architecture

## 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`

- [x] Monorepo foundation scaffolded with root workspace config, shared runtime, shared product identity, local package linking, and verification scripts
- [x] Backend migrated into `backend/` and passing typecheck, build, test, and backend verification gates
- [x] Web migrated into `web/` with shared runtime, shared kill-switch gate, shared telemetry bootstrap, normalized backend URL resolution, and platform-service-backed public auth via a compatibility shim
- [x] 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
- [x] Backend now accepts common-platform JWTs with legacy Supabase fallback and persists global trading-control state through Cosmos-backed control storage
- [x] Dynamic config now flows through backend control-plane APIs with Cosmos-first storage and legacy Supabase fallback
- [x] Mobile platform auth requests now use the common React Native platform SDK
- [x] 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, and platform-session handling, but not yet for all data-plane persistence flows
- [!] Full common-platform data-plane replacement remains a follow-up; backend and web still retain legacy Supabase data access for trading records and configuration tables

## 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. Migrate by contract, not by uncontrolled file copying.

## 4. Critical Path

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

## 5. Target Repository Shape

```text
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

- [x] `learning_ai_common_plat` package compatibility confirmed
- [x] platform-service auth behavior confirmed
- [x] platform-service kill-switch behavior confirmed
- [x] canonical product identity schema confirmed

### Internal dependencies

- [x] backend contracts available before web integration
- [x] backend contracts available before mobile integration
- [x] auth/session semantics finalized before surface wiring
- [x] 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

- [x] Create canonical product identity in `shared/product.json`
- [x] Define root `package.json`
- [x] Define `pnpm-workspace.yaml`
- [x] Define top-level scripts
- [x] Define root docs and local-dev model
- [x] Define environment model and `.env.example`
- [x] Define shared dependency strategy on local common-platform package links
- [x] Define repo conventions based on FastGap where useful
- [x] Define product IDs, ports, env prefixes, domains, and package naming
- [x] Decide mobile root folder convention
- [x] Define root workspace naming conventions
- [x] Define migration guardrails

### Deliverables

- [x] Root product metadata
- [x] Root package/workspace config
- [x] Initial repo skeleton
- [x] Environment contract
- [x] Migration design notes

### Exit Criteria

- [x] Repo structure approved
- [x] Product identity approved
- [x] Platform integration boundaries approved
- [x] 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

- [x] Define web auth pattern using `@bytelyst/react-auth`
- [x] Define mobile auth pattern using shared platform-service session contracts
- [x] Define backend auth boundary and middleware strategy
- [x] Define kill-switch semantics across web, mobile, and backend
- [x] Define ownership split between product accessibility controls and trading-behavior controls
- [x] Define telemetry envelope fields
- [ ] Define correlation ID and request propagation strategy
- [ ] Define feature flag ownership and evaluation model
- [x] Define system-of-record ownership by concern
- [x] Define degraded-platform fallback behavior
- [x] Define transitional adapters needed for legacy auth flows

### Deliverables

- [x] Auth integration spec
- [x] Kill-switch behavior spec
- [x] Telemetry and diagnostics contract
- [x] Shared config conventions

### Exit Criteria

- [x] No ambiguity remains between platform-service and product-backend responsibilities
- [x] All three surfaces have approved integration patterns
- [x] 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

- [x] Create `backend/` workspace
- [ ] Define module layout under `backend/src`
- [ ] Classify legacy backend modules as keep, refactor, or drop
- [x] 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
- [x] Normalize config loading and schema validation
- [ ] Integrate platform-aware telemetry and diagnostics
- [x] Integrate explicit kill-switch and maintenance semantics
- [x] Assign backend enforcement for global trade halt, tenant disable, and profile disable
- [x] Add runtime control endpoints
- [x] Add platform-JWT verification with legacy fallback
- [x] Add Cosmos-backed global trading-control persistence
- [-] 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
- [x] Add reconciliation and safety docs

### Keep Local

- [x] Trade execution
- [x] Strategy logic
- [x] Lifecycle and reconciliation
- [x] Capital ledger
- [x] Market and exchange integration

### Reuse from Common Platform

- [x] Auth middleware patterns
- [x] Config conventions
- [ ] Telemetry infrastructure
- [x] Diagnostics patterns

### Exit Criteria

- [x] Backend has stable typed contracts
- [x] Auth is enforced consistently
- [x] Kill-switch and control semantics are defined and testable
- [x] 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

- [x] Create `web/` workspace
- [ ] Define app shell
- [-] Replace custom auth provider with shared auth pattern
- [x] Move public auth boundary to platform-service compatibility shim
- [ ] Define route guards and role-aware rendering
- [x] Move runtime config to common conventions
- [x] Define product config
- [x] Define API client and websocket client
- [x] Standardize websocket token propagation
- [x] Integrate maintenance and kill-switch UX states
- [x] 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: `[-] In Progress`
- Priority: `High`
- Depends on: `Phase 2`

### Objective

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

### Checklist

- [x] Create Expo app structure following FastGap-style monorepo conventions
- [x] Add product config bootstrap
- [x] Integrate `@bytelyst/react-native-platform-sdk`
- [x] Implement auth flow and session restore
- [x] Define secure storage and session invalidation behavior
- [x] Implement launch-time kill-switch and maintenance handling
- [x] Add telemetry startup and error capture
- [x] Define initial mobile scope
- [x] Connect to backend and websocket/status contracts
- [ ] Add push-notification-ready architecture
- [x] Define mobile action policy for monitor-first versus control-first flows
- [x] Define alert and incident UX
- [-] Define operator-safe interventions
- [x] Define offline and degraded-state behavior

### Mobile v1 Scope

- [x] Sign in / restore session
- [x] Portfolio overview
- [x] Alerts and critical incidents
- [x] Positions
- [x] Recent history
- [x] Settings and sign out
- [x] Live state refresh via websocket with polling fallback
- [-] Safe operator controls limited to explicitly approved actions
- [x] 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

- [x] Mobile is integrated with platform auth and kill switch
- [-] Mobile consumes the same product contracts as web
- [x] 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 migration.

### Checklist

- [-] Consolidate auth/session bootstrap
- [x] Consolidate product config resolution
- [x] Consolidate request headers and token propagation helpers
- [x] Consolidate telemetry boot and event fields
- [x] Consolidate kill-switch UX and service-state handling
- [x] 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
- [x] Common code lives in the right place with clear ownership
- [x] 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

- [x] Add root verify scripts
- [ ] Add backend contract tests
- [ ] Add web auth and kill-switch smoke tests
- [ ] Add mobile launch/auth/kill-switch smoke coverage
- [x] Add docs for local dev, CI, Docker, and fallback behaviors
- [x] Define cutover sequencing from legacy repos
- [x] 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

- [x] Create root `package.json`
- [x] Create `pnpm-workspace.yaml`
- [x] Create `.env.example`
- [x] Create `shared/product.json`
- [x] Create `scripts/verify.sh` or equivalent
- [x] 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 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
- [x] Define status polling/live update strategy
- [ ] Define alert/incident UX
- [ ] Define operator-safe interventions
- [x] Define offline and degraded-state behavior

## 10. Sequencing Recommendations

### Recommended Commit Order

- [x] Repo scaffold and product identity
- [x] Backend skeleton and config/auth contracts
- [x] Backend runtime control and health contracts
- [x] Web shell and auth migration
- [x] Web dashboard migration by tab priority
- [x] Mobile bootstrap and auth
- [ ] Mobile overview/alerts/positions/history
- [ ] DRY cleanup
- [x] Verification and cutover docs

### Recommended Rollout Order

- [x] Backend internal validation
- [ ] Web internal adoption
- [ ] Mobile internal beta
- [ ] External / staged rollout

## 11. Definition of Done by Phase

- [x] Docs are updated
- [x] Contracts are explicit
- [x] Verification has been run or the remaining gap is documented
- [x] 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 becomes split between Supabase-specific flows and platform-service flows

- [ ] Mitigation: use an adapter strategy during migration
- [ ] Mitigation: define one authoritative session model early
- [ ] Mitigation: document transitional behavior explicitly

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

- [x] 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

- [x] 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

- [x] 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

- [x] Treat mobile as monitor/intervene-first for initial scope

Reason:

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

### Decision 5

- [x] 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

- [ ] 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