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