From 401671a5eb13ee5121c186209d644b11cbeb7ac5 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 4 Apr 2026 01:51:38 -0700 Subject: [PATCH] docs: strengthen trading monorepo prd and roadmap --- docs/PRD.md | 115 ++++++++++++++++++++++++++++++++++- docs/ROADMAP.md | 157 +++++++++++++++++++++++++++++++++++++++++++++--- 2 files changed, 261 insertions(+), 11 deletions(-) diff --git a/docs/PRD.md b/docs/PRD.md index ed4a078..6ccf4b4 100644 --- a/docs/PRD.md +++ b/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. diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 76e09be..2bf3a6e 100644 --- a/docs/ROADMAP.md +++ b/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.