docs: add trading monorepo prd and roadmap

2026-04-04 01:38:43 -07:00 · 2026-04-04 01:38:43 -07:00 · abcac4fa5a
commit abcac4fa5a
2 changed files with 915 additions and 0 deletions
--- a/docs/PRD.md
+++ b/docs/PRD.md
@ -0,0 +1,465 @@
+# Investment Trading Product Monorepo PRD
+
+## 1. Overview
+
+`learning_ai_invt_trdg` is the new canonical monorepo for ByteLyst's trading product line. It replaces the current fragmented setup across:
+
+- `bytelyst-trading-dashboard-web`
+- `bytelyst-trading-bot-service`
+- `bytelyst-trading-dashboard-mob`
+
+The monorepo will consolidate product surfaces into a single product architecture patterned after `learning_ai_fastgap` and integrated deeply with `learning_ai_common_plat`.
+
+This is not a lift-and-shift repo merge. It is a product and architecture reset with explicit goals:
+
+- make trading a first-class ByteLyst ecosystem product
+- remove duplicated auth, configuration, and platform integration code
+- centralize product identity and operational controls
+- preserve trading-domain moat locally while moving generic platform concerns to shared packages
+- create a cleaner foundation for regulated, multi-surface, safety-critical trading workflows
+
+## 2. Product Vision
+
+Build a unified AI-assisted trading operating system across web, mobile, and backend that gives users safe, observable, controllable, and explainable trade automation.
+
+The product should feel like one coherent system, not three separate applications:
+
+- web is the power surface for setup, monitoring, audit, and advanced control
+- mobile is the companion surface for secure monitoring, alerts, approvals, and lightweight intervention
+- backend is the execution and state authority for trading logic, reconciliation, capital controls, and lifecycle correctness
+- common platform provides the shared ecosystem rails for auth, kill switch, telemetry, flags, diagnostics, licensing, and product governance
+
+## 3. Problem Statement
+
+The current trading stack has valuable domain logic but the overall system is structurally fragmented.
+
+### 3.1 Current fragmentation
+
+- Web dashboard has custom auth/session handling and direct Supabase-heavy patterns.
+- Bot service has its own service configuration, runtime control surface, and platform boundary logic.
+- Mobile app is currently a thin UI shell without real ecosystem integration.
+- Product identity is not canonical across all surfaces.
+- Kill switch, maintenance mode, telemetry, and feature control are not treated as shared product infrastructure.
+- Some integration points between frontend and backend appear inconsistent or partially implemented.
+
+### 3.2 Why this matters
+
+This product operates in a high-trust, high-risk domain:
+
+- trading errors can lose money
+- stale state can trigger wrong actions
+- missing kill switches can turn incidents into losses
+- inconsistent auth boundaries create severe security risk
+- duplicated operational logic increases regression probability
+
+The current setup can evolve further, but not safely or efficiently at the velocity expected for a serious multi-surface product.
+
+## 4. Product Goals
+
+### 4.1 Primary goals
+
+1. Create one canonical product monorepo for the trading product.
+2. Adopt ByteLyst common-platform primitives for auth, kill switch, telemetry, feature flags, diagnostics, config, and product identity.
+3. Preserve and migrate the existing trading domain capabilities without carrying over architectural duplication.
+4. Establish backend authority boundaries and surface contracts that are explicit, typed, and testable.
+5. Support staged migration from the three legacy repos to the new monorepo with minimal production risk.
+
+### 4.2 Secondary goals
+
+1. Improve operator experience for support, incident response, and release management.
+2. Make web and mobile share a common product model and runtime semantics.
+3. Reduce future engineering cost by eliminating repeated auth/config/bootstrap code.
+4. Make the repo structurally consistent with mature ByteLyst product repos such as `learning_ai_fastgap`.
+
+## 5. Non-Goals
+
+The following are explicitly out of scope for the monorepo foundation phase:
+
+- rewriting core trading strategy logic for novelty
+- moving strategy engine, execution logic, reconciliation logic, or capital ledger logic into `learning_ai_common_plat`
+- replacing proven trading-domain logic unless required by correctness or architecture boundaries
+- building a marketplace, billing, social layer, or new AI workflow before the platform foundation is stable
+- merging all legacy history verbatim into the new repo without curation
+
+## 6. Target Users
+
+### 6.1 Retail and advanced trading users
+
+- configure strategies
+- monitor signals, entries, positions, and history
+- understand why trades did or did not execute
+- manage profile-level and account-level risk controls
+- intervene manually when necessary
+
+### 6.2 Operators and admins
+
+- pause or resume trading globally or per scope
+- inspect runtime health and reconciliation status
+- monitor telemetry, incidents, and product safety posture
+- manage maintenance windows, flags, and product rollouts
+
+### 6.3 Engineering and support teams
+
+- diagnose auth, sync, and runtime issues quickly
+- release across surfaces consistently
+- maintain a shared product contract across web, mobile, and backend
+
+## 7. Product Principles
+
+### 7.1 Safety before convenience
+
+Trading control, capital protection, kill switches, reconciliation integrity, and correct auth boundaries take precedence over UX convenience.
+
+### 7.2 One product, three surfaces
+
+Web, mobile, and backend must behave as one product with shared terminology, shared product identity, and consistent control semantics.
+
+### 7.3 Common where generic, local where differentiated
+
+Move generic platform concerns into shared packages. Keep trading-domain moat local.
+
+### 7.4 Backend authority
+
+The backend is the authority for trade execution, runtime state, safety decisions, and audit-relevant lifecycle truth. Frontends render and request; they do not become safety authorities.
+
+### 7.5 Migration without chaos
+
+The new repo should be built as the target system while the old repos remain stable references until cutover.
+
+## 8. Product Surfaces
+
+## 8.1 Web
+
+Primary responsibilities:
+
+- authenticated dashboard shell
+- strategy/profile management
+- configuration and admin control
+- observability and reconciliation views
+- lifecycle, entries, positions, history, marketplace, and settings
+- operator-grade UX for incident triage and runtime understanding
+
+Must integrate:
+
+- `@bytelyst/react-auth`
+- platform-driven kill switch / maintenance mode
+- feature flags
+- telemetry and diagnostics
+- shared product metadata
+
+## 8.2 Mobile
+
+Primary responsibilities:
+
+- secure session restore
+- launch-time kill switch handling
+- live overview, alerts, positions, and compact history
+- secure user actions for manual review/intervention
+- notification and incident awareness
+
+Must integrate:
+
+- `@bytelyst/react-native-platform-sdk`
+- platform auth and token lifecycle
+- telemetry and diagnostics
+- feature flags
+- kill switch and maintenance gate
+
+## 8.3 Backend
+
+Primary responsibilities:
+
+- market data ingestion
+- trade decision execution
+- order lifecycle and history integrity
+- reconciliation and repair flows
+- runtime control and operator safety
+- tenant/user scoping
+- API and websocket contracts for clients
+
+Must integrate:
+
+- common config and product identity conventions
+- shared auth middleware/contracts where applicable
+- platform-compatible telemetry and diagnostics
+- kill switch semantics and maintenance-aware behavior
+
+## 9. Core Product Capabilities
+
+### 9.1 Identity and access
+
+- canonical product identity via `shared/product.json`
+- user auth through shared ByteLyst platform contracts
+- role-aware access for admin and non-admin users
+- device/session aware auth state where applicable
+
+### 9.2 Safety and kill switches
+
+- product-wide kill switch
+- maintenance mode
+- global trade halt
+- profile-level or tenant-level trading disable
+- backend loop safety gates
+- clear UX behavior when the product is disabled or degraded
+
+### 9.3 Runtime observability
+
+- health, loop status, reconciliation status, and operational warnings
+- client and backend telemetry
+- correlation IDs across web, mobile, backend, and platform-service
+- diagnostics hooks for remote support and incident review
+
+### 9.4 Trading execution and lifecycle integrity
+
+- authoritative backend trade lifecycle
+- canonical orders, positions, history, and capital state
+- reconciliation and recovery flows
+- deterministic behavior under retries or restart
+- explicit lifecycle audit model
+
+### 9.5 Configuration and control
+
+- typed config schema and validation
+- environment-aware runtime configuration
+- feature-gated rollout of risky or incomplete features
+- admin controls that are secure, auditable, and reversible
+
+### 9.6 Explainability and trust
+
+- why a trade executed or did not execute
+- why a rule blocked action
+- clear distinction between user-visible summaries and backend authority decisions
+
+## 10. Product Architecture
+
+## 10.1 Desired repo structure
+
+```text
+learning_ai_invt_trdg/
+├── app/ or src/                 # Expo mobile app
+├── web/                         # Web dashboard
+├── backend/                     # Trading backend / bot service
+├── shared/
+│   └── product.json             # Canonical product identity
+├── docs/
+├── scripts/
+├── pnpm-workspace.yaml
+├── package.json
+├── docker-compose.yml
+└── .env.example
+```
+
+### 10.2 Shared dependency model
+
+The monorepo will consume `learning_ai_common_plat` packages by local workspace-style file references, following the proven FastGap pattern:
+
+- `../learning_ai_common_plat/packages/*`
+
+The product backend remains product-specific. Platform-service remains the shared destination for:
+
+- auth
+- feature flags
+- kill switch
+- telemetry
+- diagnostics
+- licensing/subscription related concerns if needed later
+
+### 10.3 Domain ownership split
+
+Keep in product repo:
+
+- trading strategy logic
+- execution manager
+- reconciliation services
+- capital ledger
+- lifecycle integrity and safety logic
+- product-specific API contracts
+- trading UI and product-specific mobile UX
+
+Move to common platform or shared package usage:
+
+- auth bootstrap
+- shared auth UI/provider patterns
+- session/token lifecycle helpers
+- product identity
+- generic telemetry and diagnostics
+- kill switch client usage
+- feature flag client usage
+- shared config loading patterns
+
+## 11. Product Identity
+
+The monorepo must define canonical product identity in `shared/product.json`.
+
+Minimum required fields:
+
+- `productId`
+- `displayName`
+- `description`
+- `domain`
+- `backendPort`
+- `bundleId`
+- `platforms`
+- `primarySurface`
+- `mobileCompanion`
+- `licensePrefix`
+- `configDirName`
+- `envVarPrefix`
+- `packageName`
+- `version`
+
+Recommended initial stance:
+
+- one product identity for the whole trading system
+- web, mobile, and backend are surfaces of the same product, not separate products
+- sub-surface names can be used operationally, but not as separate top-level product IDs
+
+## 12. Functional Requirements
+
+### 12.1 Monorepo bootstrap
+
+- root package management with pnpm
+- workspace layout similar to FastGap
+- common scripts for verify, build, lint, and test
+- environment examples and local-dev instructions
+
+### 12.2 Web requirements
+
+- authenticated web shell
+- shared auth provider integration
+- maintenance and kill-switch blocking states
+- typed API client layer for backend communication
+- websocket/session handling consistent with auth state
+- admin/operator views protected by role checks
+
+### 12.3 Mobile requirements
+
+- auth bootstrap and restore flow
+- launch-time kill switch check
+- shared telemetry startup
+- feature flag polling or refresh policy
+- secure token storage and refresh handling
+- notification-ready architecture
+
+### 12.4 Backend requirements
+
+- explicit API contract for frontend and mobile clients
+- websocket auth and tenant scoping
+- typed config schema
+- secure admin controls
+- kill-switch aware trading loop behavior
+- audit and observability hooks
+
+### 12.5 Migration requirements
+
+- preserve critical trading logic from legacy repos
+- avoid porting dead code and inconsistent glue
+- support staged cutover by surface
+- maintain production continuity during migration
+
+## 13. Non-Functional Requirements
+
+### 13.1 Security
+
+- no unauthenticated trading actions
+- no stale token trust shortcuts
+- no product control endpoints without explicit authorization
+- mobile and web behavior consistent with backend auth authority
+
+### 13.2 Reliability
+
+- restart-safe runtime behavior
+- reconciliation-safe lifecycle recovery
+- kill-switch behavior must fail safe
+- degraded platform-service conditions must have defined fallback behavior
+
+### 13.3 Observability
+
+- telemetry across all surfaces
+- structured logs with trace and correlation fields
+- auditable admin/control actions
+- backend health and safety metrics exposed consistently
+
+### 13.4 Maintainability
+
+- DRY by design for bootstrap logic
+- no parallel auth systems
+- no parallel kill-switch implementations
+- clear module ownership
+
+### 13.5 Performance
+
+- web must remain responsive under live updates
+- mobile must optimize battery/network usage
+- backend loops must not regress in latency due to platform integration
+
+## 14. Risks
+
+### 14.1 Architecture risks
+
+- carrying too much legacy shape into the new monorepo can preserve old problems
+- over-extracting domain logic into common platform can blur ownership and weaken trading safety boundaries
+
+### 14.2 Migration risks
+
+- partial migration can create double-maintained logic
+- auth changes can break web and mobile clients if backend boundaries are not stabilized first
+- kill switch semantics can become ambiguous if app maintenance mode and trade-halt mode are conflated
+
+### 14.3 Product risks
+
+- mobile may become a cosmetic mirror instead of a true product surface if not scoped clearly
+- operator workflows may remain buried in backend or docs unless explicitly designed into the product
+
+## 15. Success Metrics
+
+### 15.1 Foundation metrics
+
+- all three surfaces live in one monorepo
+- single canonical product identity exists and is used by all surfaces
+- all surfaces use common-platform auth and kill-switch integration patterns
+- zero duplicated bootstrap implementations for auth, telemetry, and kill switch
+
+### 15.2 Engineering metrics
+
+- no custom auth provider remains in web if shared provider covers the need
+- no mobile hand-rolled platform bootstrap remains for generic platform concerns
+- backend config and control boundaries are typed and documented
+
+### 15.3 Product metrics
+
+- authenticated user can sign in and restore session consistently across web and mobile
+- operator can halt product activity through defined control paths
+- users can understand state, risk, and execution outcomes from surface UX
+
+## 16. Delivery Strategy
+
+The new monorepo will be treated as the target system, not a passive archive.
+
+Recommended migration order:
+
+1. Define product identity, repo skeleton, and platform integration contracts.
+2. Stabilize backend contracts and control boundaries.
+3. Migrate or rebuild web against those contracts.
+4. Build mobile against the same contracts using the React Native platform SDK.
+5. Complete validation, observability, and cutover planning.
+
+## 17. Open Questions
+
+These must be resolved early:
+
+1. Will the trading product use one canonical product ID for all surfaces, or is there a real business reason to split mobile/web/backend identity?
+2. Which auth source remains authoritative during early migration: current Supabase-backed identity or direct platform-service identity flows?
+3. What exact kill-switch model is required?
+4. Does mobile support approve/reject/override actions, or is it monitor-first at launch?
+5. Which existing web tabs are truly product-critical for v1 of the monorepo and which should be deferred behind flags?
+
+## 18. Immediate PRD Acceptance Criteria
+
+This PRD is acceptable when the implementation roadmap it drives does all of the following:
+
+- treats the new monorepo as the source of future product evolution
+- uses FastGap as the structural template, not as a direct code clone
+- uses common platform as the shared ecosystem backbone
+- preserves trading-domain logic as product-owned
+- explicitly plans migration, safety, auth, kill switch, telemetry, and DRY cleanup
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@ -0,0 +1,450 @@
+# 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.