# 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/`                |
