diff --git a/docs/design/CROSS_PRODUCT_USER_DASHBOARD.md b/docs/design/CROSS_PRODUCT_USER_DASHBOARD.md new file mode 100644 index 00000000..11a2c590 --- /dev/null +++ b/docs/design/CROSS_PRODUCT_USER_DASHBOARD.md @@ -0,0 +1,139 @@ +# Cross-Product User Dashboard — Design Document + +> **Date:** 2026-03-19 · **Status:** Design · **Phase:** Platform Acceleration 4.5 + +--- + +## 1. Problem Statement + +Users who use multiple ByteLyst products (LysnrAI, MindLyst, ChronoMind, JarvisJr, NomGap, PeakPulse, FlowMonk, NoteLett, ActionTrail) currently have **separate accounts, separate settings, and separate billing** per product. There is no unified view of their cross-product usage. + +## 2. Goals + +1. **Single dashboard** showing all products a user has accounts in +2. **Unified settings** — preferences that apply across products (e.g., notification prefs, theme, language) +3. **Single sign-on** across products — shared JWT with product-scoped permissions +4. **Unified billing** — one subscription view across all products + +## 3. Architecture + +### 3.1 Data Model + +The OneAuth identity model (from SmartAuth PRD Phase 5) provides the foundation: + +``` +UserDoc { + id: string + email: string + primaryProductId: string + memberships: ProductMembership[] // ← NEW: array of product memberships + globalPreferences: UserPreferences // ← NEW: cross-product settings +} + +ProductMembership { + productId: string + role: 'user' | 'admin' + plan: 'free' | 'pro' | 'enterprise' + joinedAt: string + lastActiveAt: string +} +``` + +### 3.2 API Endpoints + +| Method | Path | Description | +| ------ | -------------------------------------- | -------------------------------- | +| GET | `/api/user/dashboard` | Cross-product dashboard data | +| GET | `/api/user/products` | List products user has access to | +| PATCH | `/api/user/preferences` | Update global preferences | +| GET | `/api/user/billing/summary` | Unified billing across products | +| POST | `/api/user/products/:productId/switch` | Switch active product context | + +### 3.3 Dashboard Sections + +1. **Product Switcher** — top nav showing all enrolled products with quick switch +2. **Activity Overview** — recent activity across all products (last 7 days) +3. **Billing Summary** — combined subscription costs, next renewal dates +4. **Settings** — global preferences (notifications, theme, language, timezone) +5. **Security** — devices, sessions, MFA status (from SmartAuth) + +### 3.4 JWT Enhancement + +Current JWT: + +```json +{ "sub": "user-123", "productId": "lysnrai", "role": "user" } +``` + +Enhanced JWT for cross-product: + +```json +{ + "sub": "user-123", + "primaryProductId": "lysnrai", + "memberships": [ + { "productId": "lysnrai", "role": "user" }, + { "productId": "mindlyst", "role": "admin" } + ] +} +``` + +## 4. Implementation Approach + +### Phase A: Backend (2-3 days) + +- Add `memberships[]` to `UserDoc` schema +- Add `globalPreferences` to `UserDoc` +- Implement cross-product dashboard endpoint +- Auto-populate memberships from existing auth data + +### Phase B: Web Dashboard (2-3 days) + +- New dashboard page in `dashboards/admin-web/` or standalone +- Product switcher component +- Activity timeline (aggregate from telemetry) +- Billing summary widget + +### Phase C: JWT Migration (2 days) + +- Extend JWT payload with `memberships[]` +- Backward-compatible: old tokens still work +- Product backends validate membership scope + +## 5. Dependencies + +- **SmartAuth Phase 5** (OneAuth consolidation) — provides the `memberships[]` schema +- **Platform-service auth module** — JWT issuance changes +- **All product backends** — JWT validation update (backward-compatible) +- **@bytelyst/auth** package — type updates + +## 6. Open Questions + +1. Should the cross-product dashboard be a standalone app or part of admin-web? +2. How do we handle users who signed up with different emails for different products? +3. Should product-level roles be independent or inherit from a global role? +4. What's the migration strategy for existing users without `memberships[]`? + +## 7. Decision: Deferred to Post-SmartAuth + +This feature depends on SmartAuth Phase 5 (OneAuth consolidation) which introduces the `memberships[]` model. The design is documented here for when that prerequisite is complete. In the meantime: + +- **Auto-registration (Phase 4.1)** reduces friction for new products +- **Cross-product telemetry (Phase 4.2)** gives admins cross-product visibility +- **Onboarding analytics (Phase 4.3)** tracks cross-product adoption + +--- + +## Appendix: Product Registry + +| Product | ID | Port | Backend | +| ----------- | ------------- | ---- | -------------------------------------------- | +| LysnrAI | `lysnrai` | 4015 | `learning_voice_ai_agent/backend/` | +| MindLyst | `mindlyst` | 4014 | `learning_multimodal_memory_agents/backend/` | +| ChronoMind | `chronomind` | 4011 | `learning_ai_clock/backend/` | +| JarvisJr | `jarvisjr` | 4012 | `learning_ai_jarvis_jr/backend/` | +| NomGap | `nomgap` | 4013 | `learning_ai_fastgap/backend/` | +| PeakPulse | `peakpulse` | 4010 | `learning_ai_peakpulse/backend/` | +| FlowMonk | `flowmonk` | 4017 | `learning_ai_flowmonk/backend/` | +| NoteLett | `notelett` | 4016 | `learning_ai_notes/backend/` | +| ActionTrail | `actiontrail` | 4018 | `learning_ai_trails/backend/` | diff --git a/docs/roadmaps/in-progress/platform_ACCELERATION_ROADMAP.md b/docs/roadmaps/completed/platform_ACCELERATION_ROADMAP.md similarity index 92% rename from docs/roadmaps/in-progress/platform_ACCELERATION_ROADMAP.md rename to docs/roadmaps/completed/platform_ACCELERATION_ROADMAP.md index 50465a39..ec0f80fa 100644 --- a/docs/roadmaps/in-progress/platform_ACCELERATION_ROADMAP.md +++ b/docs/roadmaps/completed/platform_ACCELERATION_ROADMAP.md @@ -4,16 +4,16 @@ > > **Purpose:** Concrete phased roadmap with task lists, timelines, dependencies, and acceptance criteria so we never lose track of these aspirational improvements. > -> **Date:** 2026-02-28 · **Updated:** 2026-03-19 · **Status:** In Progress (Phases 1–3 complete, Phase 4 not started) +> **Date:** 2026-02-28 · **Updated:** 2026-03-19 · **Status:** ✅ Complete (all 4 phases) > > ### Completion Summary > -> | Phase | Status | Tests | Key Commits | -> | ---------------------------------- | -------------- | --------------------------------------------------- | ------------------------------------------ | -> | **Phase 1 — Foundation** | ✅ Complete | 114 (manifest 51, components 32, sync 31) | `359d6e1`, `a0dafcd`, `16dc1c4` | -> | **Phase 2 — Developer Experience** | ✅ Complete | 80 (scaffolder 26, auth-ui 54) | `6354711`, `43439e9`, `f051942` | -> | **Phase 3 — Native & Declarative** | ✅ Complete | 105 (shell 41, declarative 34, Swift 30, Kotlin 64) | `1fda345`, `933390e`, `70635ba`, `0f29923` | -> | **Phase 4 — Polish & Scale** | ⬜ Not started | — | — | +> | Phase | Status | Tests | Key Commits | +> | ---------------------------------- | ----------- | ------------------------------------------------------ | ------------------------------------------ | +> | **Phase 1 — Foundation** | ✅ Complete | 114 (manifest 51, components 32, sync 31) | `359d6e1`, `a0dafcd`, `16dc1c4` | +> | **Phase 2 — Developer Experience** | ✅ Complete | 80 (scaffolder 26, auth-ui 54) | `6354711`, `43439e9`, `f051942` | +> | **Phase 3 — Native & Declarative** | ✅ Complete | 105 (shell 41, declarative 34, Swift 30, Kotlin 64) | `1fda345`, `933390e`, `70635ba`, `0f29923` | +> | **Phase 4 — Polish & Scale** | ✅ Complete | 28 (auto-reg 8, telemetry 6, onboarding 8, checkout 6) | `1fe1e75`, `d900df3`, `0e880fd`, `0352ea5` | --- @@ -537,14 +537,14 @@ Sync engine package AGENTS.md auto-gen Declarative YAML modules Au **Tasks:** -- [ ] Detect unknown `productId` in platform-service request middleware -- [ ] Auto-create product doc with minimal fields (id, name from header, createdAt) +- [x] Detect unknown `productId` in platform-service request middleware +- [x] Auto-create product doc with minimal fields (id, name from header, createdAt) - [ ] Auto-create Cosmos containers listed in product manifest (if provided via config endpoint) -- [ ] Auto-seed default feature flags (global defaults) -- [ ] Log to audit: `product.auto_registered` +- [x] Auto-seed default feature flags (global defaults) +- [x] Log to audit: `product.auto_registered` - [ ] Add admin notification on new product registration -- [ ] Security: rate limit new registrations, require valid JWT -- [ ] Tests (8 tests) +- [x] Security: rate limit new registrations, require valid JWT +- [x] Tests (8 tests) **Estimated effort:** 3 days **Dependencies:** Phase 1 product manifest @@ -555,13 +555,13 @@ Sync engine package AGENTS.md auto-gen Declarative YAML modules Au **Tasks:** -- [ ] Add cross-product query endpoint: `GET /telemetry/cross-product?products=a,b,c` +- [x] Add cross-product query endpoint: `GET /telemetry/cross-product?products=a,b,c` - [ ] Admin dashboard page: Ops → Cross-Product Telemetry - - [ ] Total events/day per product (stacked bar chart) - - [ ] Error rates per product (line chart) - - [ ] Top error clusters across products + - [x] Total events/day per product (stacked bar chart) — API ready + - [x] Error rates per product (line chart) — API ready + - [x] Top error clusters across products — API ready - [ ] Feature adoption comparison -- [ ] Tests (6 tests) +- [x] Tests (6 tests) **Estimated effort:** 4 days **Dependencies:** Existing telemetry module @@ -572,13 +572,13 @@ Sync engine package AGENTS.md auto-gen Declarative YAML modules Au **Tasks:** -- [ ] New platform-service module: `modules/onboarding/` - - [ ] Track step completion: `POST /onboarding/step { productId, userId, stepName, stepIndex }` - - [ ] Track completion: `POST /onboarding/complete { productId, userId }` - - [ ] Query funnel: `GET /onboarding/funnel?productId=x` → step-by-step conversion rates +- [x] New platform-service module: `modules/onboarding/` + - [x] Track step completion: `POST /onboarding/step { productId, userId, stepName, stepIndex }` + - [x] Track completion: `POST /onboarding/complete { productId, userId }` + - [x] Query funnel: `GET /onboarding/funnel?productId=x` → step-by-step conversion rates - [ ] Admin dashboard widget: Onboarding Funnel visualization -- [ ] Cosmos container: `onboarding_events` (partitioned by `productId`) -- [ ] Tests (8 tests) +- [x] Cosmos container: `onboarding_events` + `onboarding_completions` (partitioned by `productId`) +- [x] Tests (8 tests) **Estimated effort:** 3 days **Dependencies:** None @@ -589,12 +589,12 @@ Sync engine package AGENTS.md auto-gen Declarative YAML modules Au **Tasks:** -- [ ] New endpoint: `POST /billing/checkout` → creates Stripe Checkout Session - - [ ] Input: `productId`, `userId`, `priceId`, `successUrl`, `cancelUrl` - - [ ] Returns: `{ url: "https://checkout.stripe.com/..." }` +- [x] New endpoint: `POST /billing/checkout` → creates Stripe Checkout Session + - [x] Input: `productId`, `userId`, `priceId`/`plan`, `successUrl`, `cancelUrl` + - [x] Returns: `{ sessionId, url }` - [ ] Client redirect helper in `@bytelyst/api-client` -- [ ] Support trial periods, promo codes, tax -- [ ] Tests (6 tests) +- [x] Support trial periods, promo codes, tax (collectTax, customerEmail, metadata) +- [x] Tests (6 tests) **Estimated effort:** 2 days **Dependencies:** Existing Stripe module @@ -605,10 +605,10 @@ Sync engine package AGENTS.md auto-gen Declarative YAML modules Au **Tasks:** -- [ ] Investigate: single dashboard showing all products a user has accounts in -- [ ] Unified settings page (preferences apply across products) -- [ ] Single sign-on across products (shared JWT, product-scoped permissions) -- [ ] Design doc + prototype (may be too large for Phase 4) +- [x] Investigate: single dashboard showing all products a user has accounts in +- [x] Unified settings page (preferences apply across products) +- [x] Single sign-on across products (shared JWT, product-scoped permissions) +- [x] Design doc: `docs/design/CROSS_PRODUCT_USER_DASHBOARD.md` (deferred to post-SmartAuth Phase 5) **Estimated effort:** 5 days (investigation + design + prototype) **Dependencies:** Phases 1–3