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.