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

Checkpoint:

• Phase A completed in b73d5e9

• 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

Checkpoint:

• Phase B mobile placeholder-wrapper cleanup in 86e2da8

• 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

Checkpoint:

• Mobile runtime alignment checkpoint in 8580ad3

• Web runtime alignment checkpoint in 8340b1d

• Web review runtime checkpoint in 8bf0bb5

• Web notes/workspaces/search/review/detail 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

Checkpoint:

• Shared diagnostics/telemetry config alignment completed in 2fac1ba

• Shared artifact-view blob alignment completed in be3b439

• Shared best-effort extraction note-detail alignment completed in a7c362a

• 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

Checkpoint:

• Integrated web runtime verification completed in 5f3b32b

• 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