From 1b81489ecd09e55d9c78b4f03d245d1d4b410cc0 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Tue, 10 Mar 2026 11:33:58 -0700 Subject: [PATCH] docs(architecture): tighten review and roadmap consistency --- docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md | 20 +++++++++ .../08_ARCHITECTURE_REUSE_MASTER_ROADMAP.md | 14 +++++++ .../09_BACKEND_REUSE_ALIGNMENT_ROADMAP.md | 42 +++++++++++-------- .../10_WEB_REUSE_ALIGNMENT_ROADMAP.md | 20 +++++++-- .../11_MOBILE_REUSE_ALIGNMENT_ROADMAP.md | 21 ++++++++-- ...TFORM_SHARED_SERVICES_ALIGNMENT_ROADMAP.md | 33 ++++++++++----- 6 files changed, 113 insertions(+), 37 deletions(-) diff --git a/docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md b/docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md index c44c4cb..ab2350a 100644 --- a/docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md +++ b/docs/ARCHITECTURE_REVIEW_AND_REUSE_ROADMAP.md @@ -37,6 +37,17 @@ When making implementation decisions, prefer this ordering: - **DRY discipline:** Partial - **Readiness for multi-agent parallel work:** Moderate, but currently too dependent on scaffolds +# 0.2 What This Document Does Not Claim + +This document does **not** claim that: + +- web and mobile are already fully integrated with the product backend +- shared services are already production-verified for this repo +- DTO contracts are already unified across all surfaces +- the current roadmap set is a substitute for implementation verification + +It is a corrective architecture review and execution guide, not a claim of completion. + # 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. @@ -557,6 +568,15 @@ The phases below should be executed in order because later cleanup depends on ea - 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 +## Cross-Workstream Dependency Rule + +To avoid duplicate work or rework: + +- backend contract decisions should precede broad web/mobile contract cleanup +- identity/config cleanup should precede auth, telemetry, diagnostics, and storage work +- shared-service wiring decisions should precede large UI polish efforts that depend on those services +- any proposal to move code into `learning_ai_common_plat` should include evidence that at least one other product repo can reuse it + ## Phase A — Identity and Config Consolidation ### Goal diff --git a/docs/roadmaps/08_ARCHITECTURE_REUSE_MASTER_ROADMAP.md b/docs/roadmaps/08_ARCHITECTURE_REUSE_MASTER_ROADMAP.md index ead0ef8..67acca2 100644 --- a/docs/roadmaps/08_ARCHITECTURE_REUSE_MASTER_ROADMAP.md +++ b/docs/roadmaps/08_ARCHITECTURE_REUSE_MASTER_ROADMAP.md @@ -21,6 +21,19 @@ This roadmap tracks the execution work required to bring `learning_ai_notes` int - [ ] platform concerns come from shared `@bytelyst/*` packages or shared services where appropriate - [ ] product-specific notes logic remains local to this repo +# Baseline Already Confirmed + +- [x] Repo shape follows the expected product-repo layout (`backend/`, `web/`, `mobile/`, `docs/`, `shared/`) +- [x] Product-specific backend modules are local to this repo rather than pushed into `platform-service` +- [x] 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 @@ -71,6 +84,7 @@ This roadmap tracks the execution work required to bring `learning_ai_notes` int - [ ] route-level mock data sources - [ ] DTO contract definitions - [ ] platform integration wiring +- [ ] roadmap truth-alignment versus implementation reality # Done When diff --git a/docs/roadmaps/09_BACKEND_REUSE_ALIGNMENT_ROADMAP.md b/docs/roadmaps/09_BACKEND_REUSE_ALIGNMENT_ROADMAP.md index 3997ee7..8e0a580 100644 --- a/docs/roadmaps/09_BACKEND_REUSE_ALIGNMENT_ROADMAP.md +++ b/docs/roadmaps/09_BACKEND_REUSE_ALIGNMENT_ROADMAP.md @@ -10,23 +10,29 @@ Keep the backend strongly product-specific for notes domain logic while maximizi # 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 +- [x] `notes` module remains local +- [x] `workspaces` module remains local +- [x] `note-relationships` module remains local +- [x] `note-tasks` module remains local +- [x] `note-artifacts` module remains local +- [x] `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` +- [x] Continue using `@bytelyst/auth` +- [x] Continue using `@bytelyst/config` +- [x] Continue using `@bytelyst/cosmos` +- [x] Continue using `@bytelyst/datastore` +- [x] Continue using `@bytelyst/errors` +- [x] Continue using `@bytelyst/fastify-core` +- [x] Continue using `@bytelyst/logger` +- [x] Continue using `@bytelyst/testing` + +# Dependency Notes + +- [ ] Finalize backend contract decisions before broad web/mobile DTO cleanup +- [ ] Use this roadmap to define what must stay local before proposing any common-plat extraction +- [ ] Coordinate blob/extraction/MCP decisions with the platform/shared-services roadmap # Phase B0 — Identity and Config Alignment @@ -58,11 +64,11 @@ Keep the backend strongly product-specific for notes domain logic while maximizi - [ ] Review request tracing and error behavior against workspace standards - [ ] Replace raw stdout/stderr startup output with shared logger patterns if practical -# Non-Goals +# Guardrails -- [ ] 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 +- 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 diff --git a/docs/roadmaps/10_WEB_REUSE_ALIGNMENT_ROADMAP.md b/docs/roadmaps/10_WEB_REUSE_ALIGNMENT_ROADMAP.md index a835d6b..4c64282 100644 --- a/docs/roadmaps/10_WEB_REUSE_ALIGNMENT_ROADMAP.md +++ b/docs/roadmaps/10_WEB_REUSE_ALIGNMENT_ROADMAP.md @@ -8,6 +8,12 @@ Scope: `web/` 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. +# Baseline Already Confirmed + +- [x] `web/` follows the intended web-app direction for this product repo +- [x] `web/package.json` already consumes several shared `@bytelyst/*` packages +- [x] shared design-token usage is already part of the current web architecture + # Phase W0 — Identity and Config Alignment - [ ] Align `web/src/lib/product-config.ts` with `shared/product.json` @@ -18,12 +24,18 @@ Make the web app the strongest notes authoring/operator surface while ensuring t # 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 +- [x] Keep `@bytelyst/react-auth` as the auth provider foundation +- [x] Keep `@bytelyst/platform-client` as the platform-service client foundation +- [x] Keep `@bytelyst/telemetry-client` as telemetry foundation +- [x] Keep `@bytelyst/diagnostics-client` as diagnostics foundation - [ ] Remove demo-first auth behavior once real auth integration is stable +# Dependency Notes + +- [ ] Complete W0 before removing demo-first auth behavior +- [ ] Use backend route contracts as the source of truth for W2 and W4 +- [ ] Coordinate shared component reuse decisions with the platform/shared-services roadmap + # Phase W2 — Replace Runtime Mock Paths - [ ] Replace dashboard runtime mock data with backend-backed data diff --git a/docs/roadmaps/11_MOBILE_REUSE_ALIGNMENT_ROADMAP.md b/docs/roadmaps/11_MOBILE_REUSE_ALIGNMENT_ROADMAP.md index ba1f8cd..2347788 100644 --- a/docs/roadmaps/11_MOBILE_REUSE_ALIGNMENT_ROADMAP.md +++ b/docs/roadmaps/11_MOBILE_REUSE_ALIGNMENT_ROADMAP.md @@ -8,6 +8,12 @@ Scope: `mobile/` 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. +# Baseline Already Confirmed + +- [x] mobile follows the intended Expo / React Native MVP path +- [x] `mobile/package.json` already consumes multiple shared `@bytelyst/*` packages +- [x] `@bytelyst/offline-queue` is already part of the current mobile direction + # Phase M0 — Identity and Config Alignment - [ ] Align mobile config with `shared/product.json` @@ -17,12 +23,19 @@ Make the React Native / Expo MVP follow the ByteLyst reuse-first path more stric # 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 +- [x] Keep `@bytelyst/auth-client` as auth foundation +- [x] Keep `@bytelyst/api-client` as product-backend client foundation +- [x] Keep `@bytelyst/platform-client` as platform-service client foundation +- [x] Keep `@bytelyst/offline-queue` as queue foundation - [ ] Evaluate actual runtime adoption path for `@bytelyst/react-native-platform-sdk` +# Dependency Notes + +- [ ] Complete M0 before broad auth/storage cleanup +- [ ] Complete M2 before declaring mobile reuse alignment healthy +- [ ] Use backend contract decisions to drive M3 data-shape cleanup +- [ ] Coordinate telemetry/diagnostics/blob/extraction choices with the platform/shared-services roadmap + # Phase M2 — Remove Placeholder Local Wrappers - [ ] Delete or replace `mobile/src/lib/platform.ts` diff --git a/docs/roadmaps/12_PLATFORM_SHARED_SERVICES_ALIGNMENT_ROADMAP.md b/docs/roadmaps/12_PLATFORM_SHARED_SERVICES_ALIGNMENT_ROADMAP.md index f264566..7e69a29 100644 --- a/docs/roadmaps/12_PLATFORM_SHARED_SERVICES_ALIGNMENT_ROADMAP.md +++ b/docs/roadmaps/12_PLATFORM_SHARED_SERVICES_ALIGNMENT_ROADMAP.md @@ -10,19 +10,30 @@ Ensure `learning_ai_notes` uses shared ByteLyst platform packages and shared ser # 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` +- [x] `platform-service` +- [x] `extraction-service` +- [x] `mcp-server` +- [x] `@bytelyst/auth` +- [x] `@bytelyst/api-client` +- [x] `@bytelyst/platform-client` +- [x] `@bytelyst/react-auth` +- [x] `@bytelyst/telemetry-client` +- [x] `@bytelyst/diagnostics-client` +- [x] `@bytelyst/offline-queue` +- [x] `@bytelyst/design-tokens` - [ ] `@bytelyst/dashboard-components` +# Baseline Interpretation + +- [x] Checked items above mean the dependency/service is already part of the intended architecture or current dependency graph +- [ ] Unchecked items above mean the dependency is expected but not yet confirmed as adopted in this repo + +# Dependency Notes + +- [ ] Identity alignment must precede telemetry/diagnostics/header verification +- [ ] Platform-service and extraction-service decisions should precede broad UI claims of readiness +- [ ] Shared package adoption should not be described as complete until runtime wiring is verified + # Phase P0 — Identity and Package Alignment - [ ] Verify product identity is consistent across all shared-client usage