learning_ai_notes/docs/roadmaps/08_ARCHITECTURE_REUSE_MASTER_ROADMAP.md

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

Baseline Already Confirmed

• Repo shape follows the expected product-repo layout (backend/, web/, mobile/, docs/, shared/)
• Product-specific backend modules are local to this repo rather than pushed into platform-service
• The repo already consumes multiple @bytelyst/* packages across surfaces

Dependency Notes

• Complete R0 before broad auth/storage/telemetry changes
• Complete R1 before calling web/mobile runtime alignment complete
• Use backend contract decisions as the source of truth for R2 contract cleanup
• Use the platform/shared-services roadmap for cross-cutting service wiring decisions

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
• roadmap truth-alignment versus implementation reality

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