docs(architecture): add reuse alignment review and workstreams

docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md

@@ -0,0 +1,731 @@
+# ByteLyst Agentic Notes — Architecture Review, Gap Analysis, and Reuse-First Action Plan
+
+Version: 1.0
+Date: March 10, 2026
+Status: Draft
+Scope: `learning_ai_notes`
+Primary references:
+- `docs/PRD.md`
+- `docs/ROADMAP.md`
+- `../learning_ai_common_plat/docs/WORKSPACE_INVENTORY.md`
+- shared product manifest: `shared/product.json`
+
+# 0. How To Use This Document
+
+Use this document as the **architecture correction plan** for `learning_ai_notes`.
+
+It is intentionally different from the feature-delivery roadmaps under `docs/roadmaps/`:
+
+- the feature roadmaps track product delivery progress
+- this document tracks **reuse, boundary, DRY, and platform-alignment corrections**
+
+When making implementation decisions, prefer this ordering:
+
+1. preserve product-specific ownership for notes domain logic
+2. remove duplication where a shared package or shared service already exists
+3. do not move product-specific code into `learning_ai_common_plat` prematurely
+4. only introduce new shared abstractions when at least two product repos can benefit
+
+# 0.1 Architecture Scorecard
+
+- **Repo structure alignment:** Good
+- **Backend boundary alignment:** Good
+- **Web reuse alignment:** Partial
+- **Mobile reuse alignment:** Weak
+- **Identity/config consistency:** Weak
+- **Shared service adoption:** Partial
+- **DRY discipline:** Partial
+- **Readiness for multi-agent parallel work:** Moderate, but currently too dependent on scaffolds
+
+# 1. Executive Summary
+
+This repo is on the right architectural path, but it is not yet fully aligned with the original plan or the ByteLyst workspace best practices.
+
+The good news:
+- the repo already follows the correct high-level product-repo shape with `web/`, `mobile/`, `backend/`, `docs/`, and `shared/`
+- the backend is already using the right shared package pattern from `learning_ai_common_plat`
+- the web app is already consuming several correct `@bytelyst/*` packages
+- the mobile app is already attempting to consume the React Native acceleration path via shared packages
+- product-specific backend modules are correctly local to this repo instead of leaking into `platform-service`
+
+The main gaps:
+- product identity is inconsistent across surfaces
+- some repo-local wrappers are placeholders or duplicated configuration glue rather than stable shared-platform usage
+- web and mobile still rely on mock, fallback, or local-only behavior in places where the plan expects real product-backend integration
+- mobile is not yet following a true shared SDK pattern even though the PRD explicitly calls for reuse-first mobile delivery
+- web is not yet leveraging shared dashboard-style primitives strongly enough
+- repo-local code still contains temporary duplication in config, platform wiring, and fallback data definitions
+
+The core architectural correction is straightforward:
+
+- keep only **notes-specific domain behavior** in this repo
+- keep only **notes-specific UX** in this repo
+- move all reusable platform/client wiring to shared `@bytelyst/*` packages or shared services
+- standardize all surfaces on one product identity source of truth
+- remove placeholder wrappers once shared packages or SDK entrypoints are available
+
+The implementation priority should be:
+
+- **Priority 1**
+  - unify product identity and config
+- **Priority 2**
+  - remove fake or no-op local wrappers
+- **Priority 3**
+  - replace mock/fallback runtime paths with real backend integration
+- **Priority 4**
+  - complete shared platform-service / extraction / blob / diagnostics wiring
+- **Priority 5**
+  - harden DTO reuse and UI primitive reuse without over-centralizing notes-specific code
+
+# 2. Review Criteria
+
+This review evaluates the repo against five standards.
+
+## 2.1 Original Product Plan
+
+From the PRD and roadmap, this repo is expected to:
+- be a ByteLyst product repo, not a standalone architecture fork
+- consume shared platform capabilities from `learning_ai_common_plat`
+- keep product-specific notes logic in this repo's `backend/`
+- avoid rebuilding auth, telemetry, diagnostics, offline queue, extraction, blob, and admin infrastructure locally
+- maximize reuse across web and mobile
+
+## 2.2 Workspace Best Practices
+
+From the workspace inventory and common platform standards:
+- product repos consume shared packages via local `file:` references during development
+- product-specific backends live in the product repo
+- platform-agnostic concerns live in `learning_ai_common_plat`
+- shared services are the default integration layer for auth, diagnostics, telemetry, extraction, blob, and orchestration
+
+## 2.3 DRY / Reuse-First Rule
+
+Every concern should be classified as one of:
+- **product-specific and should stay local**
+- **shared and should come from a common package**
+- **shared and should come from a common service**
+- **temporary scaffold that should be removed once real shared integration lands**
+
+## 2.4 Product-Backend Boundary Rule
+
+The local `backend/` should only own product-specific notes APIs and domain persistence, such as:
+- notes
+- workspaces
+- note relationships
+- note tasks
+- note artifacts
+- note agent actions
+
+It should not reimplement platform-service concerns.
+
+## 2.5 Cross-Surface Consistency Rule
+
+`web/`, `mobile/`, and `backend/` should use:
+- the same product identity
+- the same service URL strategy
+- the same shared package stack where possible
+- compatible DTO shapes and integration patterns
+
+# 3. Current-State Assessment
+
+## 3.1 Repo Structure
+
+Current repo structure is fundamentally correct:
+
+- `backend/` — product-specific API surface
+- `web/` — primary authoring/operator UI
+- `mobile/` — React Native / Expo MVP path
+- `shared/` — product manifest
+- `docs/` — planning and execution documents
+
+Assessment:
+- **Structure alignment:** Good
+- **Execution maturity:** Partial
+- **Architectural cleanliness:** Mixed
+
+## 3.2 Product Identity Consistency
+
+This is the single most important drift area.
+
+### Shared manifest
+`shared/product.json` defines:
+- `productId`: `bytelyst-notes`
+- `displayName`: `ByteLyst Agentic Notes`
+
+### Backend
+`backend/src/lib/product-config.ts` correctly loads identity from `shared/product.json` using `@bytelyst/config`.
+
+### Mobile
+`mobile/src/api/config.ts` hardcodes:
+- `productId: 'bytelyst-notes'`
+
+This matches the manifest, but duplicates it.
+
+### Web
+`web/src/lib/product-config.ts` defaults to:
+- `PRODUCT_ID = 'agentic-notes'`
+
+This does **not** match the manifest or backend/mobile defaults.
+
+Assessment:
+- **Severity:** High
+- **Impact:** auth storage keys, telemetry product tagging, diagnostics identity, API headers, and platform-service consistency can drift immediately
+
+Required direction:
+- the repo must standardize on `shared/product.json` as the canonical source
+- all surface-level product config should derive from that identity rather than duplicating constants
+
+# 4. What Is Correctly Product-Specific Today
+
+These areas are correctly local to this repo and should remain here.
+
+## 4.1 Backend Domain Modules
+
+The following are product-specific and belong in `backend/`:
+- `notes`
+- `workspaces`
+- `note-relationships`
+- `note-tasks`
+- `note-artifacts`
+- `note-agent-actions`
+
+This matches the PRD and the workspace product-backend model.
+
+## 4.2 Notes-Specific UI
+
+These should remain local to the product web/mobile surfaces:
+- note editor UX
+- note detail composition
+- workspace navigation for notes
+- linked-context panels
+- review/approval surfaces that are product-local rather than platform-admin-global
+- mobile capture, note detail, approvals, and retrieval flows tailored to notes
+
+## 4.3 Notes-Specific Data Contracts
+
+These may begin local, then potentially graduate into shared packages only if another product genuinely shares the same abstractions:
+- note detail DTOs
+- relationship DTOs
+- task extraction review DTOs
+- agent-action note review DTOs
+
+# 5. What Is Already Reused Well
+
+## 5.1 Backend Shared Package Reuse
+
+The backend is already using the right reuse-first pattern.
+
+From `backend/package.json`:
+- `@bytelyst/auth`
+- `@bytelyst/config`
+- `@bytelyst/cosmos`
+- `@bytelyst/datastore`
+- `@bytelyst/errors`
+- `@bytelyst/fastify-core`
+- `@bytelyst/logger`
+- `@bytelyst/testing`
+
+This is good and should remain the template.
+
+## 5.2 Backend Bootstrap Alignment
+
+`backend/src/server.ts` correctly uses:
+- `createServiceApp`
+- `registerOptionalJwtContext`
+- `startService`
+- `jwtVerify` with issuer `bytelyst-platform`
+
+This is aligned with the established product-backend standard.
+
+## 5.3 Backend Identity Reuse
+
+`backend/src/lib/product-config.ts` correctly pulls product identity from `shared/product.json` using `loadProductIdentity()`.
+
+This is the best pattern currently in the repo.
+
+## 5.4 Web Shared Package Reuse
+
+From `web/package.json`, the app already consumes:
+- `@bytelyst/api-client`
+- `@bytelyst/auth-client`
+- `@bytelyst/design-tokens`
+- `@bytelyst/diagnostics-client`
+- `@bytelyst/platform-client`
+- `@bytelyst/react-auth`
+- `@bytelyst/telemetry-client`
+
+This is directionally correct.
+
+## 5.5 Mobile Shared Package Reuse
+
+From `mobile/package.json`, the app already consumes:
+- `@bytelyst/api-client`
+- `@bytelyst/auth-client`
+- `@bytelyst/design-tokens`
+- `@bytelyst/offline-queue`
+- `@bytelyst/platform-client`
+- `@bytelyst/react-native-platform-sdk`
+
+This is also directionally correct, even if the current runtime adoption is incomplete.
+
+# 6. Gap Analysis — Duplication, Drift, and Under-Reuse
+
+## 6.1 High-Priority Gap: Inconsistent Product Identity and Config
+
+### Evidence
+- `shared/product.json` → `bytelyst-notes`
+- `backend/src/lib/product-config.ts` → derived from shared manifest
+- `mobile/src/api/config.ts` → hardcoded `bytelyst-notes`
+- `web/src/lib/product-config.ts` → defaults to `agentic-notes`
+
+### Why this violates the plan
+The PRD explicitly calls for early product manifest definition and consistent product identity across all surfaces.
+
+### Why this violates DRY
+The same identity information is duplicated and partially inconsistent.
+
+### Required fix
+Introduce a single repo-local product identity adapter per surface, all deriving from `shared/product.json` or a build-generated equivalent.
+
+### Recommendation
+- **Keep local:** tiny product-config adapters if each runtime requires different env access semantics
+- **Do not keep local:** duplicated raw `productId` literals and display-name defaults scattered across files
+
+## 6.2 High-Priority Gap: Web Still Uses Mock Auth and Mock Data as a Core Runtime Path
+
+### Evidence
+- `web/src/lib/auth.ts` uses demo user fallback and demo access tokens
+- `web/src/lib/mock-data.ts` defines core app data
+- `web/src/lib/review-data.ts` defines mock approval queue and timeline
+- route files consume those mock data sources directly
+
+### Why this violates the plan
+The roadmap allows scaffold phases, but the PRD expects web to become the strongest end-to-end authoring and operator surface.
+
+### Why this matters for DRY
+Mock datasets are currently acting like a parallel local service layer. That risks duplicate DTOs and duplicate business assumptions.
+
+### Required fix
+- replace route-level mock usage with real product-backend clients
+- keep mocks only in tests or isolated prototyping fixtures
+
+### Recommendation
+- **Keep local:** notes-specific page composition and page components
+- **Move to shared or remove:** auth fallback/demo token behavior, route-runtime mock datasets, duplicated DTO assumptions that should instead come from API contracts
+
+## 6.3 High-Priority Gap: Mobile Contains Placeholder Local Wrappers Instead of Real Shared SDK Usage
+
+### Evidence
+- `mobile/src/lib/platform.ts` returns `false` in `isReactNativePlatformSdkReady()`
+- `mobile/src/lib/telemetry.ts` is a no-op stub
+- `mobile/src/api/config.ts` hardcodes platform/product URLs and identity
+- `mobile/src/api/workspaces.ts` returns inline mock workspaces
+- `mobile/src/api/notes.ts` falls back to local notes
+- `mobile/src/store/notes-store.ts` performs local-only draft/update behavior
+
+### Why this violates the plan
+The PRD explicitly says the React Native path should reuse the existing shared SDK/package baseline and avoid rebuilding infrastructure locally.
+
+### Why this matters for DRY
+The repo is beginning to grow a product-local mobile integration layer that duplicates concerns already meant to come from `@bytelyst/*` packages.
+
+### Required fix
+- use shared auth + API + platform primitives directly
+- delete placeholder wrappers that do not add product-specific value
+- add only the minimum notes-specific composition layer above shared clients
+
+### Recommendation
+- **Keep local:** notes-specific mobile stores and screens
+- **Replace/remove:** no-op telemetry wrapper, fake SDK readiness helper, inline mock workspace APIs, duplicated hardcoded config
+
+## 6.4 High-Priority Gap: Product Identity and Storage Prefixes Are Not Unified
+
+### Evidence
+- mobile auth storage prefix: `bytelyst-notes`
+- web auth storage prefix: `PRODUCT_ID` defaulting to `agentic-notes`
+- web local storage token reads are tied to that inconsistent ID
+
+### Impact
+This can create broken token reuse, diagnostics drift, telemetry mis-tagging, and subtle environment bugs.
+
+### Required fix
+Standardize token storage prefixes, telemetry identity, diagnostics identity, and API headers on the same canonical product ID.
+
+## 6.5 Medium-Priority Gap: Web Is Not Yet Leveraging Shared Dashboard/UI Packages Strongly Enough
+
+### Evidence
+The PRD explicitly expects reuse of dashboard/UI primitives where possible, but the current web app largely defines product-local layout and view primitives.
+
+### Assessment
+This is not automatically wrong. Some product-local UI is expected. The issue is that the repo has not yet clearly separated:
+- reusable table/list/filter/operator building blocks that should come from `@bytelyst/dashboard-components`
+- truly notes-specific UX composition that should stay local
+
+### Required fix
+Audit the current web components and classify each as:
+- shared candidate
+- product-specific component
+- temporary scaffold
+
+## 6.6 Medium-Priority Gap: Shared Service Usage Is Incomplete
+
+### Expected shared services from PRD
+- `platform-service`
+- `extraction-service`
+- `mcp-server`
+
+### Current reality
+- backend is correctly shaped for product-local APIs
+- MCP work has started and is product-appropriate
+- extraction is not yet truly wired
+- telemetry/diagnostics are only partial
+- blob support is not yet properly integrated for artifacts
+- web/mobile are not yet using platform-service as a truly integrated dependency boundary
+
+### Required fix
+Treat shared services as first-class runtime dependencies rather than future placeholders.
+
+## 6.7 Medium-Priority Gap: Backend Still Has Some Infra That Could Eventually Be Standardized More
+
+### Evidence
+- `backend/src/lib/config.ts` defines a local Zod env schema
+- `backend/src/lib/cosmos-init.ts` defines repo-local container registration
+- `backend/src/lib/datastore.ts` defines local datastore bootstrapping
+
+### Assessment
+This is mostly acceptable.
+
+Why it is acceptable:
+- product backends commonly retain self-contained config schemas
+- container definitions are product-specific
+- datastore choice and bootstrap can reasonably remain local if the shared package does not yet expose a higher-level product-backend bootstrap helper
+
+### Recommendation
+Do **not** move this blindly into common-plat unless a shared abstraction proves reusable across several product backends.
+
+## 6.8 Medium-Priority Gap: DTO Definitions Are Drifting Across Surfaces
+
+### Evidence
+- web defines local interfaces in `web/src/lib/types.ts`
+- mobile defines local API types in `mobile/src/api/notes.ts` and `mobile/src/api/workspaces.ts`
+- backend owns canonical persistence and route contracts
+
+### Risk
+Web/mobile may diverge from backend contracts over time.
+
+### Required fix
+Create a small shared repo-local `shared/contracts/` or `packages/contracts/` layer for notes-product DTOs if cross-surface duplication starts growing.
+
+Important nuance:
+- this should remain **repo-local** unless the contracts become useful to other products
+- this does **not** belong in `learning_ai_common_plat` unless it becomes product-agnostic
+
+# 7. Detailed DRY Classification Matrix
+
+## 7.1 Should Stay Product-Local
+
+- notes domain modules and repositories
+- note/workspace/task/relationship/artifact/agent-action route shapes
+- notes-specific editor, note detail, workspace detail, search UX
+- notes-specific mobile capture and retrieval UX
+- product-specific MCP tool definitions for notes
+- product-specific container list and partitioning strategy
+
+## 7.2 Should Come From Shared Packages
+
+- auth client creation primitives
+- API client primitives
+- platform-service client primitives
+- telemetry client primitives
+- diagnostics client primitives
+- offline queue primitives
+- design token source and generated outputs
+- testing helpers
+- error utilities
+- config loading helpers
+
+## 7.3 Should Come From Shared Services
+
+- auth and identity flows from `platform-service`
+- telemetry ingestion from `platform-service`
+- diagnostics ingestion from shared diagnostics infrastructure
+- blob upload/download from shared blob APIs
+- extraction and enrichment from `extraction-service`
+- MCP registration/orchestration through `mcp-server`
+
+## 7.4 Should Be Removed After Integration Lands
+
+- web demo auth fallback
+- web demo access token defaults
+- web route-runtime mock datasets used as primary data source
+- mobile no-op telemetry wrapper
+- mobile fake SDK readiness helper
+- mobile inline fallback workspaces
+- mobile fallback notes as a long-term runtime path
+
+# 8. Per-Surface Findings and Recommendations
+
+## 8.1 Backend
+
+### Verdict
+Backend is the most aligned part of the repo.
+
+### Strengths
+- correct ownership boundary
+- correct Fastify product-backend pattern
+- correct shared package usage
+- correct identity loading pattern
+- correct product-local module placement
+
+### Gaps
+- test depth is still shallow in several route modules
+- some infra logging still uses direct stdout/stderr in `cosmos-init.ts`
+- product-specific client contracts for web/mobile are not formalized enough
+
+### Action
+- keep backend architecture mostly intact
+- improve tests and contract discipline rather than rewriting structure
+
+## 8.2 Web
+
+### Verdict
+Web is structurally aligned but operationally still scaffold-heavy.
+
+### Strengths
+- correct framework
+- correct shared package direction
+- correct use of shared tokens
+- strong route shell progress
+
+### Gaps
+- mock-backed runtime
+- inconsistent product identity
+- weak shared dashboard primitive reuse
+- auth fallback behavior acting as a scaffold crutch
+
+### Action
+- unify config/identity first
+- replace mock data route by route with backend-backed clients
+- classify components into shared-worthy vs notes-specific
+
+## 8.3 Mobile
+
+### Verdict
+Mobile is the least aligned surface from a reuse-first perspective.
+
+### Strengths
+- correct Expo/RN acceleration path decision for MVP
+- correct dependency direction in `package.json`
+- correct use of `@bytelyst/auth-client`, `@bytelyst/api-client`, `@bytelyst/offline-queue`
+
+### Gaps
+- no-op local wrappers
+- hardcoded config
+- inline fallback services
+- incomplete real usage of shared RN platform capabilities
+- partial duplication of integration logic that should be centralized
+
+### Action
+- remove fake wrappers
+- directly adopt shared clients/SDK modules where available
+- keep only notes-specific state composition and UI locally
+
+## 8.4 Docs and Planning
+
+### Verdict
+The PRD is architecturally strong. Implementation is only partially aligned.
+
+### Strengths
+- correct ownership boundaries
+- correct reuse-first philosophy
+- correct service/package expectations
+
+### Gaps
+- some Phase 0 decisions remain unresolved even though scaffolding has progressed
+- implementation drift occurred before identity/config standardization
+- no dedicated architecture review doc existed before this one
+
+# 9. Action Plan Roadmap
+
+## Sequencing Rule
+
+The phases below should be executed in order because later cleanup depends on earlier identity and integration decisions:
+
+- Phase A before Phase B
+- Phase B before Phase C
+- Phase C before most of Phase D
+- Phase E can run in parallel with late Phase C / Phase D once contracts stabilize
+- Phase F should harden the final architecture rather than leading it
+
+## Phase A — Identity and Config Consolidation
+
+### Goal
+Make `shared/product.json` the real source of truth across all surfaces.
+
+### Tasks
+- unify `productId` across web/mobile/backend
+- align web default `PRODUCT_ID` to `bytelyst-notes`
+- create one product-config strategy per surface derived from the same identity inputs
+- standardize storage prefixes, telemetry product IDs, diagnostics product IDs, and API headers
+- eliminate conflicting raw literals from web/mobile code
+
+### Exit Criteria
+- no conflicting product IDs in repo code
+- auth storage prefixes are consistent
+- telemetry/diagnostics identify the same product everywhere
+
+## Phase B — Remove Placeholder Local Platform Wrappers
+
+### Goal
+Delete local wrappers that do not add product-specific value.
+
+### Tasks
+- remove or replace `mobile/src/lib/platform.ts`
+- remove or replace `mobile/src/lib/telemetry.ts`
+- audit all local wrapper files for no-op behavior
+- keep only thin composition helpers that are necessary for runtime/platform adaptation
+
+### Exit Criteria
+- no fake readiness helpers
+- no no-op telemetry wrapper
+- all remaining wrapper files have clear product-specific justification
+
+## Phase C — Real Backend Integration for Web and Mobile
+
+### Goal
+Stop using local mock/fallback data as a primary runtime path.
+
+### Tasks
+- replace web mock note/workspace/search/review runtime data with backend-backed clients
+- move mock data to test-only or prototype-only locations
+- replace mobile fallback notes and inline workspaces with real API calls
+- wire mobile note detail update persistence to the backend
+- align web/mobile DTOs with backend response contracts
+
+### Exit Criteria
+- web note list/detail/search use real APIs
+- mobile note list/detail/workspaces use real APIs
+- fallback data is no longer the normal runtime path
+
+## Phase D — Shared Platform Service Completion
+
+### Goal
+Use the common services the way the PRD intended.
+
+### Tasks
+- wire telemetry end-to-end through shared telemetry ingestion
+- wire diagnostics end-to-end through shared diagnostics transport
+- wire artifact upload/download via shared blob flows
+- wire extraction-backed note enrichment and task extraction through `extraction-service`
+- connect product MCP tools cleanly into shared `mcp-server` operational patterns
+
+### Exit Criteria
+- telemetry/diagnostics are real, not scaffolded
+- artifacts use shared blob infrastructure
+- extraction is best-effort but real
+- MCP integration is aligned with shared orchestration patterns
+
+## Phase E — Shared UI / Contract Hygiene
+
+### Goal
+Reduce unnecessary duplication across surfaces.
+
+### Tasks
+- classify web components into product-specific vs reusable
+- adopt `@bytelyst/dashboard-components` where appropriate
+- introduce a repo-local shared contracts module if DTO duplication expands further
+- eliminate repeated type definitions that describe the same backend objects differently
+
+### Exit Criteria
+- common UI primitives are reused where sensible
+- product-specific UX remains local
+- DTO duplication is controlled and intentional
+
+## Phase F — Backend Hardening Without Over-Abstracting
+
+### Goal
+Improve backend quality while preserving the correct ownership model.
+
+### Tasks
+- add route behavior tests using `inject()`
+- add repository behavior tests
+- add cross-entity tests
+- replace raw stdout/stderr startup logging with shared logger patterns if practical
+- only upstream common abstractions into `learning_ai_common_plat` if at least two product repos genuinely need them
+
+### Exit Criteria
+- backend is product-specific, well-tested, and not over-engineered into premature shared abstractions
+
+# 10. Concrete File-Level Recommendations
+
+## 10.1 Change Soon
+
+- `web/src/lib/product-config.ts`
+  - align to canonical identity
+- `web/src/lib/auth.ts`
+  - remove demo-first runtime path after real auth wiring lands
+- `web/src/lib/mock-data.ts`
+  - move toward test/prototype usage only
+- `web/src/lib/review-data.ts`
+  - move toward test/prototype usage only
+- `mobile/src/api/config.ts`
+  - stop hardcoding identity and URLs long term
+- `mobile/src/lib/platform.ts`
+  - delete or replace with real SDK wiring
+- `mobile/src/lib/telemetry.ts`
+  - replace with shared telemetry client integration
+- `mobile/src/api/workspaces.ts`
+  - replace inline return values with real API integration
+- `mobile/src/api/notes.ts`
+  - remove long-term fallback behavior from the primary runtime path
+
+## 10.2 Keep Local
+
+- `backend/src/modules/**`
+- `backend/src/lib/cosmos-init.ts`
+- `backend/src/lib/datastore.ts`
+- notes-specific page/screen components
+- notes-specific MCP tool definitions
+
+## 10.3 Consider Later if Duplication Grows
+
+- repo-local shared contracts package for notes DTOs
+- repo-local shared product-config helper consumed by web/mobile build pipelines
+- shared notes client package inside this repo only if multiple local surfaces need one canonical TS client
+
+# 11. Recommended Guardrails Going Forward
+
+- every new local wrapper file must justify why a shared package or service is insufficient
+- every new config literal must be checked against `shared/product.json`
+- every new web/mobile integration should prefer shared `@bytelyst/*` clients first
+- every new backend abstraction should be asked: is this truly product-specific, or should it live in common-plat?
+- no mock/fallback runtime path should be marked complete in roadmap docs unless the real integration exists
+- avoid moving product contracts into common-plat unless they are truly product-agnostic
+
+# 12. Final Verdict
+
+`learning_ai_notes` is **architecturally promising but only partially aligned** with the original reuse-first plan.
+
+The backend is already closest to the ByteLyst standard.
+The web app is structurally correct but still too scaffold-driven.
+The mobile app has the largest reuse gap because it contains temporary local wrappers and fallback services instead of a true shared-platform integration path.
+
+The repo does **not** need a major rewrite.
+It needs a disciplined cleanup and consolidation pass:
+- unify identity
+- remove placeholder wrappers
+- replace runtime mocks/fallbacks with real integrations
+- keep notes-specific code local
+- keep platform/shared concerns in `learning_ai_common_plat`
+
+That path will bring the repo back into alignment with the PRD, roadmap, DRY principles, and the established workspace architecture.
+
+# 13. Companion Execution Docs
+
+Use these checkbox-based execution docs to operationalize this review by workstream:
+
+- `docs/roadmaps/08_ARCHITECTURE_REUSE_MASTER_ROADMAP.md`
+- `docs/roadmaps/09_BACKEND_REUSE_ALIGNMENT_ROADMAP.md`
+- `docs/roadmaps/10_WEB_REUSE_ALIGNMENT_ROADMAP.md`
+- `docs/roadmaps/11_MOBILE_REUSE_ALIGNMENT_ROADMAP.md`
+- `docs/roadmaps/12_PLATFORM_SHARED_SERVICES_ALIGNMENT_ROADMAP.md`

docs/roadmaps/08_ARCHITECTURE_REUSE_MASTER_ROADMAP.md

@@ -0,0 +1,80 @@
+# Architecture Reuse Master Roadmap
+
+Status: Draft
+Parent: `docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md`
+Scope: Whole repo architecture alignment
+
+# Purpose
+
+This roadmap tracks the execution work required to bring `learning_ai_notes` into tighter alignment with:
+
+- `docs/PRD.md`
+- `docs/ROADMAP.md`
+- `shared/product.json`
+- `../learning_ai_common_plat/docs/WORKSPACE_INVENTORY.md`
+
+# Workstream Goals
+
+- [ ] one canonical product identity across all surfaces
+- [ ] no placeholder wrapper files without clear product-specific justification
+- [ ] web and mobile use real product-backend integrations rather than scaffold-first runtime paths
+- [ ] platform concerns come from shared `@bytelyst/*` packages or shared services where appropriate
+- [ ] product-specific notes logic remains local to this repo
+
+# Phase R0 — Identity and Boundary Lock
+
+- [ ] Confirm `shared/product.json` is the canonical product identity source
+- [ ] Align web product identity defaults with `shared/product.json`
+- [ ] Align mobile product identity defaults with `shared/product.json`
+- [ ] Standardize auth storage prefixes across web and mobile
+- [ ] Standardize telemetry and diagnostics product tagging
+- [ ] Document which code must remain product-local
+- [ ] Document which concerns must come from common platform packages/services
+
+# Phase R1 — Placeholder and Duplication Cleanup
+
+- [ ] Inventory all repo-local platform/config/wrapper files
+- [ ] Delete or replace wrapper files that are no-op or fake readiness scaffolds
+- [ ] Remove duplicated raw product identity literals
+- [ ] Remove long-term runtime dependence on route-level mock/fallback datasets
+- [ ] Reduce duplicate DTO definitions where they describe the same backend object
+
+# Phase R2 — Runtime Integration Alignment
+
+- [ ] Web notes/workspaces/search/reviews use real product-backend clients
+- [ ] Mobile notes/workspaces/detail flows use real product-backend clients
+- [ ] Mobile editing persists to the backend instead of local-only state
+- [ ] Artifact flows use shared blob-backed integration
+- [ ] Extraction-backed enrichment uses shared extraction service
+
+# Phase R3 — Shared Platform Completion
+
+- [ ] Telemetry uses shared ingestion and correct product tagging
+- [ ] Diagnostics uses shared ingestion and correct product tagging
+- [ ] Blob flows are shared-service-backed
+- [ ] MCP integration stays aligned with shared `mcp-server` orchestration
+- [ ] Feature flag and optional platform-service integrations are explicitly decided
+
+# Phase R4 — Hardening and Verification
+
+- [ ] Backend behavior tests prove actual route behavior, not only registration
+- [ ] Web tests cover integrated route behavior for key note flows
+- [ ] Mobile tests cover integrated API/store behavior for key note flows
+- [ ] Shared service smoke checks are documented
+- [ ] Architecture docs and delivery docs remain consistent
+
+# High-Collision Areas
+
+- [ ] `shared/product.json`
+- [ ] web/mobile product config files
+- [ ] auth storage and token handling
+- [ ] route-level mock data sources
+- [ ] DTO contract definitions
+- [ ] platform integration wiring
+
+# Done When
+
+- [ ] architecture review findings are resolved or explicitly deferred
+- [ ] repo-local code is clearly product-specific or thin shared-package composition
+- [ ] no major identity/config drift remains
+- [ ] web/mobile/backend are aligned on shared platform usage strategy

docs/roadmaps/09_BACKEND_REUSE_ALIGNMENT_ROADMAP.md

@@ -0,0 +1,72 @@
+# Backend Reuse Alignment Roadmap
+
+Status: Draft
+Parent: `docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md`
+Scope: `backend/`
+
+# Goal
+
+Keep the backend strongly product-specific for notes domain logic while maximizing reuse of ByteLyst shared packages and avoiding premature extraction of notes-specific code into common platform layers.
+
+# Preserve As Product-Local
+
+- [ ] `notes` module remains local
+- [ ] `workspaces` module remains local
+- [ ] `note-relationships` module remains local
+- [ ] `note-tasks` module remains local
+- [ ] `note-artifacts` module remains local
+- [ ] `note-agent-actions` module remains local
+
+# Shared Package Alignment
+
+- [ ] Continue using `@bytelyst/auth`
+- [ ] Continue using `@bytelyst/config`
+- [ ] Continue using `@bytelyst/cosmos`
+- [ ] Continue using `@bytelyst/datastore`
+- [ ] Continue using `@bytelyst/errors`
+- [ ] Continue using `@bytelyst/fastify-core`
+- [ ] Continue using `@bytelyst/logger`
+- [ ] Continue using `@bytelyst/testing`
+
+# Phase B0 — Identity and Config Alignment
+
+- [ ] Keep `shared/product.json` as the backend identity source
+- [ ] Ensure all persisted docs use the canonical product identity field
+- [ ] Review backend env schema for any duplicated or drifting product constants
+- [ ] Keep service URLs explicit for platform/extraction/MCP dependencies
+
+# Phase B1 — Shared-Service Boundary Discipline
+
+- [ ] Confirm no platform-service concern is being reimplemented locally
+- [ ] Keep auth/identity concerns delegated to shared platform patterns
+- [ ] Keep extraction logic delegated to `extraction-service`
+- [ ] Keep blob authorization/upload patterns delegated to shared blob/platform flows
+- [ ] Keep MCP orchestration compatible with shared `mcp-server`
+
+# Phase B2 — Contract and DTO Hygiene
+
+- [ ] Review backend response shapes used by web/mobile
+- [ ] Identify DTO duplication across backend/web/mobile
+- [ ] Introduce a repo-local shared contracts layer only if duplication becomes costly
+- [ ] Do not move notes-specific contracts to common platform unless another product clearly needs them
+
+# Phase B3 — Hardening
+
+- [ ] Add route behavior tests using Fastify `inject()`
+- [ ] Add repository behavior tests
+- [ ] Add cross-entity tests for notes + relationships/tasks/artifacts/agent actions
+- [ ] Review request tracing and error behavior against workspace standards
+- [ ] Replace raw stdout/stderr startup output with shared logger patterns if practical
+
+# Non-Goals
+
+- [ ] Do not move notes-specific modules into `platform-service`
+- [ ] Do not create shared abstractions that only benefit this one product
+- [ ] Do not over-generalize the notes domain into common platform prematurely
+
+# Done When
+
+- [ ] backend remains clearly product-specific
+- [ ] shared package usage is explicit and clean
+- [ ] backend contracts are stable enough for web/mobile integration
+- [ ] backend quality is improved without architectural drift

docs/roadmaps/10_WEB_REUSE_ALIGNMENT_ROADMAP.md

@@ -0,0 +1,70 @@
+# Web Reuse Alignment Roadmap
+
+Status: Draft
+Parent: `docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md`
+Scope: `web/`
+
+# Goal
+
+Make the web app the strongest notes authoring/operator surface while ensuring that shared platform concerns come from common ByteLyst packages and services rather than repo-local duplication or long-term scaffold behavior.
+
+# Phase W0 — Identity and Config Alignment
+
+- [ ] Align `web/src/lib/product-config.ts` with `shared/product.json`
+- [ ] Standardize auth storage prefix with backend/mobile identity
+- [ ] Standardize telemetry product tagging
+- [ ] Standardize diagnostics product tagging
+- [ ] Remove conflicting default `productId` values
+
+# Phase W1 — Auth and Platform Reuse
+
+- [ ] Keep `@bytelyst/react-auth` as the auth provider foundation
+- [ ] Keep `@bytelyst/platform-client` as the platform-service client foundation
+- [ ] Keep `@bytelyst/telemetry-client` as telemetry foundation
+- [ ] Keep `@bytelyst/diagnostics-client` as diagnostics foundation
+- [ ] Remove demo-first auth behavior once real auth integration is stable
+
+# Phase W2 — Replace Runtime Mock Paths
+
+- [ ] Replace dashboard runtime mock data with backend-backed data
+- [ ] Replace workspaces runtime mock data with backend-backed data
+- [ ] Replace note detail runtime mock data with backend-backed data
+- [ ] Replace search runtime mock data with backend-backed data
+- [ ] Replace reviews runtime mock data with backend-backed data
+- [ ] Restrict `mock-data.ts` and `review-data.ts` to tests/prototyping only
+
+# Phase W3 — Shared UI and Component Reuse
+
+- [ ] Audit current web components for possible `@bytelyst/dashboard-components` reuse
+- [ ] Keep notes-specific editor and review UX local
+- [ ] Reuse shared list/filter/empty-state/operator primitives where sensible
+- [ ] Avoid copying shared dashboard patterns into product-local components unnecessarily
+
+# Phase W4 — Contract and DTO Hygiene
+
+- [ ] Align route data shapes with backend response contracts
+- [ ] Reduce duplicate type definitions that restate backend objects differently
+- [ ] Introduce a repo-local shared contracts layer only if duplication becomes significant
+
+# Phase W5 — Integrated Verification
+
+- [ ] Add tests for integrated note list/detail/search flows
+- [ ] Add tests for integrated review/approval surfaces once backend-backed
+- [ ] Verify telemetry and diagnostics initialization against real shared service endpoints
+- [ ] Verify no long-term runtime dependence on mock tokens or mock auth state
+
+# High-Collision Areas
+
+- [ ] `web/src/lib/product-config.ts`
+- [ ] `web/src/lib/auth.ts`
+- [ ] `web/src/lib/mock-data.ts`
+- [ ] `web/src/lib/review-data.ts`
+- [ ] route files under `web/src/app/(app)/`
+- [ ] shared type definitions
+
+# Done When
+
+- [ ] web uses real backend integrations for core notes workflows
+- [ ] web uses shared platform packages for platform concerns
+- [ ] notes-specific UX remains local without unnecessary duplication
+- [ ] auth/config/telemetry/diagnostics are identity-consistent

docs/roadmaps/11_MOBILE_REUSE_ALIGNMENT_ROADMAP.md

@@ -0,0 +1,71 @@
+# Mobile Reuse Alignment Roadmap
+
+Status: Draft
+Parent: `docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md`
+Scope: `mobile/`
+
+# Goal
+
+Make the React Native / Expo MVP follow the ByteLyst reuse-first path more strictly by removing temporary local wrapper code and relying on shared clients and shared platform capabilities wherever available.
+
+# Phase M0 — Identity and Config Alignment
+
+- [ ] Align mobile config with `shared/product.json`
+- [ ] Remove hardcoded raw identity values where a canonical source can be used
+- [ ] Standardize auth storage prefix with web/backend
+- [ ] Standardize platform/product base URL strategy
+
+# Phase M1 — Shared Client and SDK Alignment
+
+- [ ] Keep `@bytelyst/auth-client` as auth foundation
+- [ ] Keep `@bytelyst/api-client` as product-backend client foundation
+- [ ] Keep `@bytelyst/platform-client` as platform-service client foundation
+- [ ] Keep `@bytelyst/offline-queue` as queue foundation
+- [ ] Evaluate actual runtime adoption path for `@bytelyst/react-native-platform-sdk`
+
+# Phase M2 — Remove Placeholder Local Wrappers
+
+- [ ] Delete or replace `mobile/src/lib/platform.ts`
+- [ ] Delete or replace `mobile/src/lib/telemetry.ts`
+- [ ] Audit other local helper files for no-op or placeholder behavior
+- [ ] Keep only thin product-specific composition helpers that add real value
+
+# Phase M3 — Replace Fallback Runtime Paths
+
+- [ ] Replace fallback notes as the primary runtime path
+- [ ] Replace inline workspace returns with real API calls
+- [ ] Persist note edits to the backend
+- [ ] Align mobile note detail with real backend fields
+- [ ] Ensure approval/activity flows use real backend-backed data where intended
+
+# Phase M4 — Shared Platform Completion
+
+- [ ] Wire real telemetry through shared client/runtime path
+- [ ] Wire diagnostics if supported on the selected RN path
+- [ ] Keep blob/extraction/feature flag integrations on shared-platform rails
+- [ ] Avoid creating product-local substitutes for shared platform capabilities
+
+# Phase M5 — Verification
+
+- [ ] Add tests for auth/bootstrap behavior
+- [ ] Add tests for API wrapper behavior
+- [ ] Add tests for store behavior under real backend contracts
+- [ ] Add smoke tests for note list/detail/edit flows
+
+# High-Collision Areas
+
+- [ ] `mobile/src/api/config.ts`
+- [ ] `mobile/src/api/auth.ts`
+- [ ] `mobile/src/api/client.ts`
+- [ ] `mobile/src/api/notes.ts`
+- [ ] `mobile/src/api/workspaces.ts`
+- [ ] `mobile/src/lib/platform.ts`
+- [ ] `mobile/src/lib/telemetry.ts`
+- [ ] mobile stores that assume local-only persistence
+
+# Done When
+
+- [ ] mobile relies primarily on shared clients and shared platform capabilities
+- [ ] no fake wrapper files remain
+- [ ] no inline workspace or long-term fallback note runtime remains
+- [ ] notes-specific mobile UX remains local and intentional

docs/roadmaps/12_PLATFORM_SHARED_SERVICES_ALIGNMENT_ROADMAP.md

@@ -0,0 +1,74 @@
+# Platform and Shared Services Alignment Roadmap
+
+Status: Draft
+Parent: `docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md`
+Scope: cross-cutting shared service/package adoption
+
+# Goal
+
+Ensure `learning_ai_notes` uses shared ByteLyst platform packages and shared services consistently and intentionally, while keeping the local repo focused on notes-specific product logic and UX.
+
+# Core Shared Inputs
+
+- [ ] `platform-service`
+- [ ] `extraction-service`
+- [ ] `mcp-server`
+- [ ] `@bytelyst/auth`
+- [ ] `@bytelyst/api-client`
+- [ ] `@bytelyst/platform-client`
+- [ ] `@bytelyst/react-auth`
+- [ ] `@bytelyst/telemetry-client`
+- [ ] `@bytelyst/diagnostics-client`
+- [ ] `@bytelyst/offline-queue`
+- [ ] `@bytelyst/design-tokens`
+- [ ] `@bytelyst/dashboard-components`
+
+# Phase P0 — Identity and Package Alignment
+
+- [ ] Verify product identity is consistent across all shared-client usage
+- [ ] Verify storage prefixes and headers are consistent across shared-client usage
+- [ ] Verify no repo-local code is duplicating shared package responsibilities unnecessarily
+
+# Phase P1 — Platform-Service Alignment
+
+- [ ] Real auth flow is aligned with platform-service expectations
+- [ ] Telemetry flow is aligned with platform-service ingestion
+- [ ] Diagnostics flow is aligned with shared diagnostics ingestion
+- [ ] Feature flag needs are explicitly decided
+- [ ] Blob authorization/upload flows are explicitly decided
+
+# Phase P2 — Extraction-Service Alignment
+
+- [ ] Summarization integration path is defined
+- [ ] Metadata enrichment path is defined
+- [ ] Task extraction path is defined
+- [ ] Fallback behavior is defined for extraction failures
+- [ ] Product routes/UI do not invent a parallel AI enrichment path
+
+# Phase P3 — MCP-Server Alignment
+
+- [ ] Product-side note tools remain product-specific
+- [ ] Shared `mcp-server` registration/orchestration remains the execution gateway
+- [ ] Product/tool auth boundaries remain aligned with shared server expectations
+- [ ] Request/correlation propagation expectations remain aligned
+
+# Phase P4 — Shared UI / Token / Contract Discipline
+
+- [ ] Shared design tokens remain the only theme source
+- [ ] No new hardcoded colors or isolated token systems are introduced
+- [ ] Shared dashboard components are used where sensible
+- [ ] Notes-specific contracts stay local unless clearly reusable by another product
+
+# Phase P5 — Verification and Docs
+
+- [ ] Shared-service smoke checks are documented
+- [ ] Shared-package usage is documented by surface
+- [ ] Explicit deferrals are documented where shared capability exists but is not yet wired
+- [ ] Architecture review doc and delivery roadmaps remain consistent
+
+# Done When
+
+- [ ] shared packages/services are the default source for platform concerns
+- [ ] local repo code is clearly product-specific or thin composition
+- [ ] no major platform duplication remains
+- [ ] the repo is easier to parallelize without architectural drift