docs: strengthen trading monorepo prd and roadmap

docs/PRD.md

@@ -29,6 +29,15 @@ The product should feel like one coherent system, not three separate application
 - 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
 
+### 2.1 Product Positioning
+
+Working positioning:
+
+- serious trading operations product
+- AI-assisted, but not AI-unbounded
+- operator-safe and backend-authoritative
+- ecosystem-native inside ByteLyst, not a one-off exception
+
 ## 3. Problem Statement
 
 The current trading stack has valuable domain logic but the overall system is structurally fragmented.
@@ -184,6 +193,29 @@ Must integrate:
 - platform-compatible telemetry and diagnostics
 - kill switch semantics and maintenance-aware behavior
 
+## 8.4 Platform-Service vs Product-Backend Boundary
+
+Platform-service owns:
+
+- product-aware auth primitives
+- feature flags
+- kill switch and maintenance controls
+- telemetry ingestion and diagnostics hooks
+- shared product metadata and cross-product policy controls
+
+Trading backend owns:
+
+- trading state authority
+- orders, positions, lifecycle, and reconciliation authority
+- runtime loop controls
+- trading admin operations and domain audit events
+
+Web and mobile own:
+
+- authenticated presentation
+- user and operator interaction flows
+- clear communication of degraded, halted, or maintenance states
+
 ## 9. Core Product Capabilities
 
 ### 9.1 Identity and access
@@ -230,6 +262,28 @@ Must integrate:
 - why a rule blocked action
 - clear distinction between user-visible summaries and backend authority decisions
 
+### 9.7 Product Scope by Release
+
+Foundation release scope:
+
+- monorepo structure
+- canonical product identity
+- shared platform integration model
+- backend-first contract stabilization
+
+Product v1 scope:
+
+- authenticated web dashboard
+- authenticated mobile monitor surface
+- backend authority for trading state and controls
+- overview, alerts, positions, history, and runtime controls
+
+Deferred:
+
+- full mobile parity with advanced web strategy management
+- nonessential novelty features
+- product expansion outside the core trading workflow
+
 ## 10. Product Architecture
 
 ## 10.1 Desired repo structure
@@ -264,7 +318,17 @@ The product backend remains product-specific. Platform-service remains the share
 - diagnostics
 - licensing/subscription related concerns if needed later
 
-### 10.3 Domain ownership split
+### 10.3 Legacy Source Mapping
+
+Migration source mapping:
+
+- `bytelyst-trading-dashboard-web` -> `web/`
+- `bytelyst-trading-bot-service` -> `backend/`
+- `bytelyst-trading-dashboard-mob` -> mobile `app/` or `src/`
+
+This mapping is conceptual, not a requirement to copy files literally. Valuable domain logic and product UX should be ported. Duplicate bootstrap code and dead weight should not.
+
+### 10.4 Domain ownership split
 
 Keep in product repo:
 
@@ -287,6 +351,15 @@ Move to common platform or shared package usage:
 - feature flag client usage
 - shared config loading patterns
 
+### 10.5 System of Record Decisions
+
+Recommended authority model:
+
+- platform-service is the source of truth for platform-level identity and controls
+- trading backend is the source of truth for runtime trading state
+- durable domain state comes from backend-managed database and exchange reconciliation
+- web and mobile caches are convenience layers only
+
 ## 11. Product Identity
 
 The monorepo must define canonical product identity in `shared/product.json`.
@@ -357,6 +430,15 @@ Recommended initial stance:
 - support staged cutover by surface
 - maintain production continuity during migration
 
+### 12.6 Critical User Journeys
+
+1. A user signs in on web and sees only authorized, scoped trading state.
+2. A user signs in on mobile and restores the same scoped state.
+3. An operator pauses or resumes trading and all surfaces reflect the state clearly.
+4. A user can understand why a trade fired, was blocked, or was skipped.
+5. The backend restarts and rebuilds authoritative lifecycle state without silent drift.
+6. During maintenance or kill-switch activation, each surface behaves consistently and safely.
+
 ## 13. Non-Functional Requirements
 
 ### 13.1 Security
@@ -393,6 +475,28 @@ Recommended initial stance:
 - mobile must optimize battery/network usage
 - backend loops must not regress in latency due to platform integration
 
+### 13.6 Documentation and Operational Clarity
+
+- operator controls must be documented
+- kill-switch semantics must be documented
+- cutover and rollback paths must be documented
+- repo ownership and module boundaries must be understandable without tribal knowledge
+
+### 13.7 Constraints and Assumptions
+
+Constraints:
+
+- legacy repos remain active references during migration
+- common-platform integration should use existing shared packages where possible
+- safety-critical trading behavior cannot tolerate ambiguous ownership boundaries
+
+Assumptions:
+
+- one canonical product identity across surfaces is acceptable
+- platform-service remains the home for generic ecosystem services
+- Supabase-heavy flows may need transitional adapters before final convergence
+- mobile should launch as monitor/intervene-first rather than parity-first
+
 ## 14. Risks
 
 ### 14.1 Architecture risks
@@ -432,6 +536,15 @@ Recommended initial stance:
 - operator can halt product activity through defined control paths
 - users can understand state, risk, and execution outcomes from surface UX
 
+### 15.4 Launch Quality Gates
+
+- backend auth boundaries are enforced and tested
+- trade-halt and maintenance behavior are tested
+- session restore works on web and mobile
+- websocket auth and scoping are validated
+- telemetry identifiers are present across surfaces
+- rollback and cutover procedures are documented
+
 ## 16. Delivery Strategy
 
 The new monorepo will be treated as the target system, not a passive archive.

docs/ROADMAP.md

@@ -18,6 +18,16 @@ It assumes:
 4. Do not preserve legacy repo boundaries inside the new monorepo if they block clarity.
 5. Migrate by contract, not by uncontrolled file copying.
 
+### 2.1 Second-Pass Review Improvements
+
+This revision tightens:
+
+- system-of-record clarity
+- migration mapping from legacy repos
+- phase exit criteria
+- cutover realism
+- dependency visibility
+
 ## 3. Target Repository Shape
 
 ```text
@@ -81,8 +91,26 @@ learning_ai_invt_trdg/
 - docs
 - rollout readiness
 
+### 4.7 Migration and cutover management
+
+- legacy source inventory
+- selective import strategy
+- staged cutover plan
+- rollback planning
+
 ## 5. Phase Plan
 
+### 5.1 Critical Path
+
+The critical path is:
+
+- product identity
+- shared platform contract
+- backend authority
+- web migration
+- mobile migration
+- verification and cutover
+
 ## Phase 0: Product Definition and Monorepo Foundation
 
 ### Objective
@@ -97,6 +125,8 @@ Create a credible target repository with clear product identity and explicit int
 - 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
+- decide mobile root folder convention
+- define root workspace naming conventions
 
 ### Deliverables
 
@@ -111,6 +141,7 @@ Create a credible target repository with clear product identity and explicit int
 - repo structure is approved
 - product identity is approved
 - platform integration boundaries are approved
+- migration guardrails are approved
 
 ## Phase 1: Shared Platform Contract Layer
 
@@ -127,6 +158,9 @@ Ensure all surfaces adopt one consistent platform model for auth, kill switch, t
 - 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 fallback behavior
+- define transitional adapters needed for legacy auth flows
 
 ### Deliverables
 
@@ -139,6 +173,7 @@ Ensure all surfaces adopt one consistent platform model for auth, kill switch, t
 
 - there is no ambiguity about platform-service versus product-backend responsibilities
 - all three surfaces have approved integration patterns
+- auth and kill-switch semantics are implementation-ready
 
 ## Phase 2: Backend First Migration
 
@@ -161,6 +196,8 @@ The trading product is safety-critical. Web and mobile must align around a stabl
 - integrate explicit kill-switch and maintenance semantics
 - standardize admin controls and audit logging
 - document deprecated endpoints and legacy compatibility strategy
+- classify legacy backend modules as keep, refactor, or drop
+- define durable state ownership between memory, database, and exchange sync
 
 ### Keep local
 
@@ -182,6 +219,7 @@ The trading product is safety-critical. Web and mobile must align around a stabl
 - 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
 
@@ -200,6 +238,8 @@ Move the web dashboard onto the new repo and onto shared platform bootstrap patt
 - gate unfinished tabs/features behind flags
 - define admin/operator routes and role-based controls
 - normalize terminology, models, and UI behavior around backend authority
+- classify each current web tab as ship, defer, or redesign
+- remove legacy bootstrap duplication instead of porting it
 
 ### Priority order
 
@@ -214,6 +254,7 @@ Move the web dashboard onto the new repo and onto shared platform bootstrap patt
 - 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
 
@@ -232,6 +273,8 @@ Build mobile as a real ecosystem surface, not a mock UI shell.
 - define initial mobile scope
 - connect to backend and websocket/status contracts
 - add push-notification-ready architecture
+- define secure storage and session invalidation behavior
+- define mobile action policy for monitor-first versus control-first flows
 
 ### Mobile v1 scope recommendation
 
@@ -253,6 +296,7 @@ Build mobile as a real ecosystem surface, not a mock UI shell.
 
 - 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
 
@@ -268,6 +312,7 @@ Remove duplicated implementation patterns exposed during migration.
 - consolidate telemetry boot and event fields
 - consolidate kill-switch UX and service-state handling
 - consolidate shared types for product contracts
+- remove temporary migration-only adapters that are no longer needed
 
 ### Guardrail
 
@@ -277,6 +322,7 @@ Only extract code reused by at least two surfaces or clearly generic across Byte
 
 - 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
 
@@ -293,15 +339,52 @@ Validate that the new monorepo is safer and more coherent than the legacy setup
 - add docs for local dev, CI, Docker, and fallback behaviors
 - define cutover sequencing from legacy repos
 - define rollback paths
+- define a 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
 
-## 6. Detailed Work Breakdown
+## 6. Legacy Repo Migration Map
 
-## 6.1 Root / repository tasks
+### `bytelyst-trading-dashboard-web`
+
+Destination:
+
+- `web/` application shell, components, hooks, and product-facing client logic
+
+Rule:
+
+- preserve valuable product UI and domain-facing client logic
+- replace custom auth/bootstrap and duplicated platform plumbing
+
+### `bytelyst-trading-bot-service`
+
+Destination:
+
+- `backend/` modules, services, and trading-domain infrastructure
+
+Rule:
+
+- preserve domain and safety logic
+- normalize config, auth boundaries, telemetry, and runtime control
+
+### `bytelyst-trading-dashboard-mob`
+
+Destination:
+
+- root mobile app structure and mobile product components
+
+Rule:
+
+- treat current mobile repo as design/input source, not final architecture
+
+## 7. Detailed Work Breakdown
+
+## 7.1 Root / repository tasks
 
 - create root `package.json`
 - create `pnpm-workspace.yaml`
@@ -310,8 +393,9 @@ Validate that the new monorepo is safer and more coherent than the legacy setup
 - create `scripts/verify.sh` or equivalent
 - create root README
 - create docker/dev orchestration model
+- define naming conventions and import boundaries
 
-## 6.2 Backend tasks
+## 7.2 Backend tasks
 
 - define module layout under `backend/src`
 - split generic lib concerns from trading-domain modules
@@ -320,8 +404,10 @@ Validate that the new monorepo is safer and more coherent than the legacy setup
 - add runtime control endpoints
 - add telemetry and health integration
 - add reconciliation and safety docs
+- define websocket auth model and namespaces
+- define admin audit event schema
 
-## 6.3 Web tasks
+## 7.3 Web tasks
 
 - define app shell
 - define auth bootstrap
@@ -329,8 +415,9 @@ Validate that the new monorepo is safer and more coherent than the legacy setup
 - 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
 
-## 6.4 Mobile tasks
+## 7.4 Mobile tasks
 
 - define Expo structure
 - define navigation shell
@@ -338,8 +425,23 @@ Validate that the new monorepo is safer and more coherent than the legacy setup
 - define status polling/live update strategy
 - define alert/incident UX
 - define operator-safe interventions
+- define offline and degraded-state behavior
 
-## 7. Sequencing Recommendations
+## 8. Dependency Matrix
+
+Upstream dependencies:
+
+- `learning_ai_common_plat` package compatibility
+- platform-service auth and kill-switch behavior
+- canonical product identity decision
+
+Internal dependencies:
+
+- backend contracts block web and mobile
+- auth/session semantics block all surfaces
+- kill-switch semantics block operator UX and release readiness
+
+## 9. Sequencing Recommendations
 
 ### Recommended commit order at implementation time
 
@@ -360,7 +462,16 @@ Validate that the new monorepo is safer and more coherent than the legacy setup
 3. mobile internal beta
 4. external/staged rollout
 
-## 8. Risks and Mitigations
+## 10. Definition of Done by Phase
+
+Each phase is done only when:
+
+- 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
+
+## 11. Risks and Mitigations
 
 ### Risk: legacy assumptions leak into the new architecture
 
@@ -401,7 +512,23 @@ Mitigation:
 
 - keep trading logic local unless there is proven reuse
 
-## 9. Decision Log
+## 12. Cutover Strategy
+
+Recommended cutover approach:
+
+1. build target contracts in the new repo
+2. validate backend behavior in isolation
+3. migrate internal web usage
+4. release mobile in controlled beta
+5. switch operational ownership only after monitoring and support confidence is established
+
+Avoid:
+
+- big-bang replacement
+- silent endpoint swaps
+- prolonged dual-maintenance of business logic
+
+## 13. Decision Log
 
 ### Decision 1
 
@@ -430,7 +557,17 @@ Reason:
 
 - avoids duplicated auth, kill switch, telemetry, config, and diagnostics work
 
-## 10. Acceptance Criteria for This Roadmap
+### Decision 4
+
+Treat mobile as monitor/intervene-first for initial scope.
+
+Reason:
+
+- improves delivery realism
+- reduces safety risk
+- avoids false parity with web
+
+## 14. Acceptance Criteria for This Roadmap
 
 This roadmap is successful if it can guide implementation without ambiguity on:
 
@@ -442,7 +579,7 @@ This roadmap is successful if it can guide implementation without ambiguity on:
 - DRY extraction rules
 - risk controls
 
-## 11. Recommended Immediate Next Steps
+## 15. Recommended Immediate Next Steps
 
 1. Approve PRD and roadmap direction.
 2. Scaffold the root monorepo structure.