From abcac4fa5a53dedc9c14672ef121781953864c89 Mon Sep 17 00:00:00 2001 From: Saravana Achu Mac Date: Sat, 4 Apr 2026 01:38:43 -0700 Subject: [PATCH] docs: add trading monorepo prd and roadmap --- docs/PRD.md | 465 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/ROADMAP.md | 450 ++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 915 insertions(+) create mode 100644 docs/PRD.md create mode 100644 docs/ROADMAP.md diff --git a/docs/PRD.md b/docs/PRD.md new file mode 100644 index 0000000..ed4a078 --- /dev/null +++ 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 diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md new file mode 100644 index 0000000..76e09be --- /dev/null +++ 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.