From d15f19441f616eb33d87e3435a5a3ec2f28fe9d9 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Sat, 28 Feb 2026 21:37:19 -0800 Subject: [PATCH] docs: add platform acceleration implementation roadmap with phased task lists --- .../PLATFORM_ACCELERATION_ROADMAP.md | 736 ++++++++++++++++++ 1 file changed, 736 insertions(+) create mode 100644 docs/BEST_PRACTICES/PLATFORM_ACCELERATION_ROADMAP.md diff --git a/docs/BEST_PRACTICES/PLATFORM_ACCELERATION_ROADMAP.md b/docs/BEST_PRACTICES/PLATFORM_ACCELERATION_ROADMAP.md new file mode 100644 index 00000000..30875a72 --- /dev/null +++ b/docs/BEST_PRACTICES/PLATFORM_ACCELERATION_ROADMAP.md @@ -0,0 +1,736 @@ +# Platform Acceleration — Implementation Roadmap + +> **Companion to:** [PLATFORM_ACCELERATION_IDEAS.md](./PLATFORM_ACCELERATION_IDEAS.md) +> +> **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 · **Status:** Planned + +--- + +## Table of Contents + +1. [Overview & Phasing](#1-overview--phasing) +2. [Phase 1 — Foundation (Weeks 1–2)](#2-phase-1--foundation-weeks-12) +3. [Phase 2 — Developer Experience (Weeks 3–6)](#3-phase-2--developer-experience-weeks-36) +4. [Phase 3 — Native & Declarative (Weeks 7–12)](#4-phase-3--native--declarative-weeks-712) +5. [Phase 4 — Polish & Scale (Weeks 13–16)](#5-phase-4--polish--scale-weeks-1316) +6. [Dependency Graph](#6-dependency-graph) +7. [Success Metrics](#7-success-metrics) +8. [Risk Register](#8-risk-register) + +--- + +## 1. Overview & Phasing + +``` +Phase 1 (Wk 1-2) Phase 2 (Wk 3-6) Phase 3 (Wk 7-12) Phase 4 (Wk 13-16) +───────────────── ───────────────── ────────────────── ────────────────── +Product manifest CLI scaffolder Native Swift SDK Multi-product telemetry +Module generator Auth UI kit Native Kotlin SDK Onboarding analytics +Shared UI components API route generator Dashboard shell Pre-built Stripe checkout +Sync engine package AGENTS.md auto-gen Declarative YAML modules Auto-registration + Cross-product dashboards +``` + +**Target outcome:** New product from zero → deployed MVP in **under 8 hours**. + +--- + +## 2. Phase 1 — Foundation (Weeks 1–2) + +> **Theme:** Build the primitives that everything else depends on. + +### 2.1 Product Manifest Specification (`product.json`) + +**What:** Define a JSON schema that captures everything about a product — identity, theme, features, containers, flags, ports. + +**Location:** `packages/config/src/product-manifest.ts` + +**Tasks:** + +- [ ] Design `product.json` JSON schema (Zod) +- [ ] Define fields: `id`, `name`, `bundleId`, `domain`, `description`, `platforms[]`, `theme{}`, `features{}`, `cosmos.containers{}`, `defaultFlags[]`, `ports{}` +- [ ] Add `loadProductManifest(path)` function to `@bytelyst/config` +- [ ] Add validation: all required fields, valid productId format, no duplicate container names +- [ ] Write tests (8–10 tests) +- [ ] Create `product.json` files for existing products: LysnrAI, MindLyst, ChronoMind, NomGap +- [ ] Document the schema in README + +**Acceptance Criteria:** + +- `loadProductManifest('./product.json')` returns typed, validated config +- Existing products have valid manifests +- Schema is extensible (unknown keys don't fail validation) + +**Estimated effort:** 2 days +**Dependencies:** None +**Blocks:** Phase 2 CLI scaffolder, Phase 4 auto-registration + +--- + +### 2.2 Module Generator (`pnpm gen:module`) + +**What:** A script that generates the standard `types.ts → repository.ts → routes.ts → test.ts` module from a field definition. + +**Location:** `services/platform-service/scripts/gen-module.ts` + +**Tasks:** + +- [ ] Design CLI interface: `pnpm gen:module --name --fields "" --partition ` +- [ ] Support field types: `string`, `number`, `boolean`, `date`, `datetime`, `enum(a,b,c)`, `string[]`, `number[]` +- [ ] Support optional fields with `?` suffix (e.g., `dueAt:datetime?`) +- [ ] Generate `types.ts` with Zod schemas (`Create*Schema`, `Update*Schema`) and TypeScript interface +- [ ] Generate `repository.ts` with list/get/create/update/delete functions +- [ ] Generate `routes.ts` with GET (list), GET/:id, POST, PATCH/:id, DELETE/:id +- [ ] Generate `.test.ts` with tests for all CRUD operations +- [ ] Auto-add container to `cosmos-init.ts` CONTAINER_DEFS +- [ ] Auto-add route import + registration to `server.ts` +- [ ] Add `--dry-run` flag to preview output without writing files +- [ ] Write tests for the generator itself (template rendering) +- [ ] Add `gen:module` script to platform-service `package.json` + +**Acceptance Criteria:** + +- `pnpm gen:module --name tasks --fields "title:string,status:enum(pending,active,done),priority:number" --partition userId` produces 4 valid files +- Generated code passes `pnpm typecheck` and `pnpm test` with no modifications +- Container automatically appears in `cosmos-init.ts` +- Route automatically registered in `server.ts` + +**Estimated effort:** 2 days +**Dependencies:** None +**Blocks:** Phase 3 declarative YAML modules + +--- + +### 2.3 Shared UI Components Package + +**What:** Extract identical components used across all dashboards into a shared package. + +**Location:** `packages/dashboard-components/` + +**Tasks:** + +- [ ] Create `packages/dashboard-components/` package structure +- [ ] Extract `ErrorPage` component (currently copy-pasted in admin-web, tracker-web, user-dashboard-web) +- [ ] Extract `NotFoundPage` component +- [ ] Extract `LoadingSpinner` / `LoadingSkeleton` component +- [ ] Extract `EmptyState` component (icon + title + description + CTA) +- [ ] Extract `PageHeader` component (title + breadcrumbs + actions) +- [ ] Make all components theme-aware (accept CSS custom properties) +- [ ] Write Storybook-like visual tests or snapshot tests +- [ ] Update admin-web to consume from `@bytelyst/dashboard-components` +- [ ] Update tracker-web to consume +- [ ] Update user-dashboard-web to consume +- [ ] Add package to `pnpm-workspace.yaml` +- [ ] Document usage in README + +**Acceptance Criteria:** + +- All 3 dashboards import from `@bytelyst/dashboard-components` instead of local copies +- Components render correctly with each dashboard's theme +- Zero visual regression (screenshots match before/after) + +**Estimated effort:** 2 days +**Dependencies:** None +**Blocks:** Phase 3 dashboard shell + +--- + +### 2.4 Sync Engine Package (`@bytelyst/sync`) + +**What:** Extract the offline-first sync pattern into a reusable package with configurable entities, conflict strategies, and storage adapters. + +**Location:** `packages/sync/` + +**Tasks:** + +- [ ] Audit existing sync implementations: + - [ ] ChronoMind: `web/src/lib/platform-sync.ts` (~200 lines), `use-sync.ts` + - [ ] NomGap: `src/lib/offline-queue.ts` (~150 lines), store sync in `fasting-store.ts` + - [ ] MindLyst: `PlatformSyncManager.kt`, `PlatformApiClient.kt` +- [ ] Design unified API: + ```typescript + createSyncEngine({ productId, entities, storage, apiClient, onConflict }) + engine.push(entity, data) + engine.delete(entity, id) + engine.pull() → Promise + engine.fullSync() → Promise + engine.getQueueLength() → number + engine.onStatusChange(callback) + ``` +- [ ] Implement offline queue with configurable storage adapter: + - [ ] `LocalStorageAdapter` (web) + - [ ] `MMKVAdapter` (React Native) — interface only, consumer provides MMKV instance + - [ ] `InMemoryAdapter` (testing) +- [ ] Implement retry with exponential backoff (max 5 attempts, configurable) +- [ ] Implement conflict detection (timestamp-based) +- [ ] Implement conflict strategies: `server-wins`, `client-wins`, `last-write-wins`, `manual` +- [ ] Implement queue deduplication (collapse multiple updates to same entity) +- [ ] Implement connectivity detection (`navigator.onLine` + custom event) +- [ ] Implement auto-flush on reconnect +- [ ] Integrate with `@bytelyst/telemetry-client` (track sync success/failure/conflicts) +- [ ] Write comprehensive tests (20+ tests): + - [ ] Queue persistence across "restarts" + - [ ] Retry behavior + - [ ] Conflict resolution for each strategy + - [ ] Deduplication + - [ ] Connectivity changes +- [ ] Migrate ChronoMind web to use `@bytelyst/sync` (prove it works) +- [ ] Document API, storage adapters, conflict strategies + +**Acceptance Criteria:** + +- `createSyncEngine()` returns a working engine with all methods +- Offline queue persists across page reloads (localStorage adapter) +- Conflicts detected and resolved per configured strategy +- ChronoMind web successfully migrated (no regression) +- 20+ tests passing + +**Estimated effort:** 3 days +**Dependencies:** `@bytelyst/api-client` (already exists) +**Blocks:** Phase 3 native SDKs (Swift/Kotlin port) + +--- + +## 3. Phase 2 — Developer Experience (Weeks 3–6) + +> **Theme:** Tools that eliminate scaffolding and boilerplate for new products. + +### 3.1 CLI Scaffolder (`@bytelyst/create-app`) + +**What:** Interactive CLI that generates a fully wired product repo from a product manifest. + +**Location:** `packages/create-app/` + +**Tasks:** + +- [ ] Create package structure with `bin/create-app.ts` entry point +- [ ] Implement interactive prompts (using `@inquirer/prompts` or `prompts`): + - [ ] Product name, ID, bundle ID, domain + - [ ] Platform selection: Web (Next.js), Expo (React Native), iOS (SwiftUI), Android (Compose) + - [ ] Feature selection: Auth, Billing, Telemetry, Feature Flags, Offline Sync, Push Notifications + - [ ] User dashboard: Yes/No +- [ ] Create template directory structure: + - [ ] `templates/nextjs-web/` — Next.js 16 App Router with all `src/lib/` wiring + - [ ] `templates/expo-rn/` — Expo SDK with router, Zustand, MMKV + - [ ] `templates/swiftui-ios/` — SwiftUI scaffold with services + - [ ] `templates/compose-android/` — Jetpack Compose scaffold + - [ ] `templates/agents-md/` — AGENTS.md template + - [ ] `templates/shared/` — .gitignore, .env.example, README.md, CLAUDE.md +- [ ] Implement template engine (simple `{{VARIABLE}}` replacement + conditional blocks) +- [ ] Implement `product.json` generation from prompts +- [ ] Implement auto-registration: + - [ ] POST to platform-service `/products` to register product + - [ ] Add containers to `cosmos-init.ts` (or via API) + - [ ] Seed default feature flags +- [ ] Implement git init + first commit +- [ ] Add `--from product.json` flag to skip prompts and use existing manifest +- [ ] Add `--dry-run` flag +- [ ] Write tests for template rendering and manifest generation +- [ ] Publish as `npx @bytelyst/create-app` + +**Acceptance Criteria:** + +- Running `npx @bytelyst/create-app` interactively produces a buildable repo +- `--from product.json` produces same result non-interactively +- Generated Next.js app starts with `npm run dev` immediately +- Generated AGENTS.md is complete and accurate +- All `src/lib/` wiring files have correct product ID + +**Estimated effort:** 5 days +**Dependencies:** Phase 1 product manifest +**Blocks:** None (but enables faster onboarding) + +--- + +### 3.2 Auth UI Kit (`@bytelyst/auth-ui`) + +**What:** Shared React components for auth flows — login, register, forgot password, email verification, SSO. + +**Location:** `packages/auth-ui/` + +**Tasks:** + +- [ ] Create package structure +- [ ] Design component API (props interface for each component): + - [ ] `` + - [ ] `` + - [ ] `` + - [ ] `` + - [ ] `` + - [ ] `` +- [ ] Implement `LoginPage`: + - [ ] Email + password form with validation + - [ ] "Remember me" checkbox + - [ ] SSO buttons (Google, Apple, Microsoft) — configurable + - [ ] "Forgot password" link + - [ ] "Create account" link + - [ ] Loading/error states +- [ ] Implement `RegisterPage`: + - [ ] Name, email, password, confirm password + - [ ] Terms checkbox + - [ ] Password strength indicator +- [ ] Implement `ForgotPasswordPage` → `ResetPasswordPage` flow +- [ ] Implement `VerifyEmailPage` with code input +- [ ] Implement `OnboardingShell` — step indicator, navigation, progress bar +- [ ] Wire all components to `@bytelyst/auth-client` internally +- [ ] Theme support: dark/light, custom accent colors via CSS custom properties +- [ ] Responsive design (mobile + desktop) +- [ ] Accessibility (ARIA labels, keyboard navigation, screen reader) +- [ ] Write tests (component rendering, form validation, submission flow) +- [ ] Migrate one existing product's auth pages to use the kit (prove it works) + +**Acceptance Criteria:** + +- `` handles full login flow including error states +- Components work with any product's theme +- All forms validate client-side before submission +- Accessible (passes axe-core audit) +- One product successfully migrated + +**Estimated effort:** 5 days +**Dependencies:** `@bytelyst/auth-client` (already exists) +**Blocks:** None + +--- + +### 3.3 API Route Generator + +**What:** CLI to generate Next.js App Router API routes from entity definitions. + +**Location:** `packages/create-app/src/generators/api-routes.ts` (or standalone script) + +**Tasks:** + +- [ ] Design CLI: `npx @bytelyst/gen:api-route --name tasks --methods GET,POST,PATCH,DELETE` +- [ ] Generate `src/app/api//route.ts` with GET (list) + POST (create) +- [ ] Generate `src/app/api//[id]/route.ts` with GET (detail) + PATCH + DELETE +- [ ] Include standard patterns: auth check, Zod validation, error handling, rate limiting +- [ ] Support `--with-handler` flag to wrap with `apiHandler()` HOF +- [ ] Write tests for generated output + +**Acceptance Criteria:** + +- Generated routes pass TypeScript type-check +- Routes include auth, validation, error handling +- `--with-handler` wraps routes in error handler HOF + +**Estimated effort:** 2 days +**Dependencies:** None +**Blocks:** None + +--- + +### 3.4 AGENTS.md Auto-Generator + +**What:** Generate AGENTS.md from `product.json` + repo scan. + +**Location:** `packages/create-app/src/generators/agents-md.ts` + +**Tasks:** + +- [ ] Scan repo directory structure (glob pattern) +- [ ] Read `product.json` for identity, stack, conventions +- [ ] Count test files and estimate test count +- [ ] List key files per domain (auto-detect from directory names) +- [ ] Generate markdown from template with all sections: + - [ ] Project identity table + - [ ] Repo layout tree + - [ ] Tech stack table + - [ ] Coding conventions (inherited from ByteLyst + product-specific) + - [ ] File ownership map + - [ ] Build & test commands + - [ ] Common pitfalls +- [ ] Output to `AGENTS.md` + symlinks: `CLAUDE.md`, `.cursorrules`, `.windsurfrules` +- [ ] Add `--update` flag to refresh without overwriting custom sections +- [ ] Add to `/repo_update-agent-docs` workflow + +**Acceptance Criteria:** + +- Generated AGENTS.md matches quality of hand-written ones +- `--update` preserves custom sections (marked with `` fences) +- All 4 agent doc files stay in sync + +**Estimated effort:** 2 days +**Dependencies:** Phase 1 product manifest +**Blocks:** None + +--- + +## 4. Phase 3 — Native & Declarative (Weeks 7–12) + +> **Theme:** Eliminate boilerplate for native apps and backend CRUD entirely. + +### 4.1 Native Swift SDK (`ByteLystSDK`) + +**What:** A Swift Package providing auth, telemetry, feature flags, and sync for all iOS/macOS/watchOS apps. + +**Location:** New repo: `bytelyst-ios-sdk/` (or `packages/ios-sdk/` in common-plat) + +**Tasks:** + +- [ ] Create Swift Package structure with targets: `ByteLystSDK`, `ByteLystSDKTests` +- [ ] Implement `ByteLystPlatform` entry point: + ```swift + let platform = ByteLystPlatform(config: .init( + productId: "peakpulse", + baseUrl: "https://api.peakpulse.app", + authStorage: KeychainTokenStorage() + )) + ``` +- [ ] **Auth module:** + - [ ] `platform.auth.login(email:password:)` → `AuthResult` + - [ ] `platform.auth.register(name:email:password:)` → `AuthResult` + - [ ] `platform.auth.logout()` + - [ ] `platform.auth.currentUser` → `User?` + - [ ] Token storage in Keychain + - [ ] Silent token refresh +- [ ] **Telemetry module:** + - [ ] `platform.telemetry.track(eventType:module:eventName:tags:metrics:)` + - [ ] Background queue with batching (max 50 events or 30s interval) + - [ ] Flush on app background / terminate + - [ ] Install ID persistence in UserDefaults + - [ ] Session ID rotation on app foreground +- [ ] **Feature flags module:** + - [ ] `platform.flags.isEnabled(key:)` → `Bool` + - [ ] `platform.flags.value(key:)` → `String?` + - [ ] Background polling (configurable interval, default 5 min) + - [ ] Local cache in UserDefaults + - [ ] Override support for development +- [ ] **Sync module:** + - [ ] `platform.sync.register(entity:endpoint:conflictStrategy:)` + - [ ] `platform.sync.push(entity:data:)` + - [ ] `platform.sync.pull()` → `SyncResult` + - [ ] Offline queue in UserDefaults (or file-based for large payloads) + - [ ] Retry with exponential backoff +- [ ] **HTTP layer:** + - [ ] URLSession-based with auth header injection + - [ ] Request ID propagation + - [ ] Timeout + retry for idempotent requests +- [ ] Audit existing Swift code across products: + - [ ] ChronoMind: `Shared/Cloud/PlatformSyncManager.swift`, `Shared/Notifications/` + - [ ] LysnrAI: `LysnrAI/Services/TelemetryService.swift`, auth flow + - [ ] MindLyst: no iOS SDK yet (uses KMP) +- [ ] Write XCTests (30+ tests) +- [ ] Migrate ChronoMind iOS to use `ByteLystSDK` (prove it works) +- [ ] Document setup, usage, and migration guide + +**Acceptance Criteria:** + +- Single `import ByteLystSDK` gives access to auth, telemetry, flags, sync +- All modules work offline (queue/cache) and sync when online +- ChronoMind iOS successfully migrated +- 30+ tests passing +- Works on iOS 16+, macOS 14+, watchOS 10+ + +**Estimated effort:** 8 days +**Dependencies:** Phase 1 sync engine (for design parity) +**Blocks:** None + +--- + +### 4.2 Native Kotlin SDK (`com.bytelyst.sdk`) + +**What:** Equivalent of the Swift SDK for Android/Wear OS. + +**Location:** New module or repo for Kotlin SDK + +**Tasks:** + +- [ ] Create Kotlin library module structure +- [ ] Implement `ByteLystPlatform` entry point (mirror Swift API) +- [ ] **Auth module** (OkHttp + kotlinx.serialization) +- [ ] **Telemetry module** (coroutine-based batching) +- [ ] **Feature flags module** (SharedPreferences cache) +- [ ] **Sync module** (offline queue in SharedPreferences or Room) +- [ ] **HTTP layer** (OkHttp interceptor for auth + request ID) +- [ ] Audit existing Kotlin code: + - [ ] ChronoMind: `app/.../sync/PlatformApiClient.kt`, `SyncRepository.kt` + - [ ] NomGap: `src/api/client.ts` (React Native, different approach) +- [ ] Write JUnit5 tests (25+ tests) +- [ ] Migrate ChronoMind Android to use SDK +- [ ] Document setup and usage + +**Acceptance Criteria:** + +- Same API surface as Swift SDK +- Works with Jetpack Compose and traditional Android +- 25+ tests passing +- ChronoMind Android migrated + +**Estimated effort:** 6 days +**Dependencies:** Phase 1 sync engine (for design parity) +**Blocks:** None + +--- + +### 4.3 Universal Dashboard Shell (`@bytelyst/dashboard-shell`) + +**What:** A configurable Next.js layout with built-in pages for profile, billing, settings, notifications. + +**Location:** `packages/dashboard-shell/` + +**Tasks:** + +- [ ] Create package structure +- [ ] Implement `` layout component: + - [ ] Responsive sidebar (collapsible on mobile) + - [ ] Top bar with user avatar + dropdown + - [ ] Breadcrumbs + - [ ] Theme toggle (dark/light) + - [ ] Keyboard shortcut support (`Cmd+K` search, `Cmd+,` settings) +- [ ] Implement built-in pages: + - [ ] `/profile` — view/edit user profile, avatar upload + - [ ] `/billing` — current plan, Stripe customer portal link, payment history + - [ ] `/settings` — notification preferences, units, theme, data export + - [ ] `/notifications` — notification preference toggles +- [ ] Configuration via props: + - [ ] `productName`, `logo`, `navItems[]`, `features{}` + - [ ] Feature flags: `billing: true/false`, `profile: true/false`, etc. +- [ ] Wire to `@bytelyst/auth-client` for user context +- [ ] Wire to `@bytelyst/api-client` for platform-service calls +- [ ] Theme support via CSS custom properties +- [ ] Write tests (component rendering, navigation, responsive behavior) +- [ ] Migrate user-dashboard-web to use shell (prove it works) +- [ ] Document configuration options + +**Acceptance Criteria:** + +- `` renders full layout +- Built-in pages are functional (not just stubs) +- Responsive on mobile +- user-dashboard-web successfully migrated + +**Estimated effort:** 8 days +**Dependencies:** Phase 1 shared UI components, Phase 2 auth UI kit +**Blocks:** None + +--- + +### 4.4 Declarative YAML Backend Modules + +**What:** Define backend CRUD modules as YAML files; runtime generates Fastify routes automatically. + +**Location:** `services/platform-service/src/lib/declarative-loader.ts` + +**Tasks:** + +- [ ] Design YAML schema for module definitions: + - [ ] Entity name, container, partition key + - [ ] Field definitions with types, validation rules, defaults + - [ ] Endpoint definitions with method, path, auth requirements + - [ ] Custom endpoint stubs (`custom: true`) +- [ ] Implement YAML parser + Zod schema validator for module definitions +- [ ] Implement runtime route generator: + - [ ] Read all `.module.yaml` files from a `modules/declarative/` directory + - [ ] Generate Fastify routes at startup (no code generation — runtime interpretation) + - [ ] Apply standard patterns: auth, validation, error handling, audit logging + - [ ] Support filtering, sorting, pagination for list endpoints +- [ ] Implement standard CRUD handlers: + - [ ] List with filtering + sorting + pagination + - [ ] Get by ID + - [ ] Create with validation + - [ ] Update (partial) with validation + - [ ] Delete +- [ ] Support custom endpoints (generate handler stubs in a `custom/` directory) +- [ ] Auto-register containers in Cosmos +- [ ] Write comprehensive tests (15+ tests) +- [ ] Migrate one simple existing module to YAML as proof (e.g., `changelog`) +- [ ] Document YAML schema and usage + +**Acceptance Criteria:** + +- A `.module.yaml` file with no TypeScript produces working CRUD endpoints +- Standard CRUD operations work correctly (create, read, update, delete, list) +- Custom endpoints generate stub files for manual implementation +- One existing module successfully migrated +- No performance regression vs hand-written modules + +**Estimated effort:** 8 days +**Dependencies:** Phase 1 module generator (informs schema design) +**Blocks:** None + +--- + +## 5. Phase 4 — Polish & Scale (Weeks 13–16) + +> **Theme:** Cross-product visibility, zero-touch provisioning, and final polish. + +### 5.1 Auto-Registration on First Request + +**Tasks:** + +- [ ] Detect unknown `productId` in platform-service request middleware +- [ ] 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` +- [ ] Add admin notification on new product registration +- [ ] Security: rate limit new registrations, require valid JWT +- [ ] Tests (8 tests) + +**Estimated effort:** 3 days +**Dependencies:** Phase 1 product manifest + +--- + +### 5.2 Multi-Product Telemetry Dashboard + +**Tasks:** + +- [ ] 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 + - [ ] Feature adoption comparison +- [ ] Tests (6 tests) + +**Estimated effort:** 4 days +**Dependencies:** Existing telemetry module + +--- + +### 5.3 Shared Onboarding Analytics + +**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 +- [ ] Admin dashboard widget: Onboarding Funnel visualization +- [ ] Cosmos container: `onboarding_events` (partitioned by `productId`) +- [ ] Tests (8 tests) + +**Estimated effort:** 3 days +**Dependencies:** None + +--- + +### 5.4 Pre-Built Stripe Checkout Flow + +**Tasks:** + +- [ ] New endpoint: `POST /billing/checkout` → creates Stripe Checkout Session + - [ ] Input: `productId`, `userId`, `priceId`, `successUrl`, `cancelUrl` + - [ ] Returns: `{ url: "https://checkout.stripe.com/..." }` +- [ ] Client redirect helper in `@bytelyst/api-client` +- [ ] Support trial periods, promo codes, tax +- [ ] Tests (6 tests) + +**Estimated effort:** 2 days +**Dependencies:** Existing Stripe module + +--- + +### 5.5 Cross-Product User Dashboard + +**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) + +**Estimated effort:** 5 days (investigation + design + prototype) +**Dependencies:** Phases 1–3 + +--- + +## 6. Dependency Graph + +``` +product.json (P1.1) + │ + ├──→ CLI scaffolder (P2.1) + │ ├──→ AGENTS.md auto-gen (P2.4) + │ └──→ API route generator (P2.3) + │ + ├──→ Auto-registration (P4.1) + │ + └──→ Design token generation (existing) + +Module generator (P1.2) + │ + └──→ Declarative YAML modules (P3.4) + +Shared UI components (P1.3) + │ + └──→ Dashboard shell (P3.3) + │ + └──→ Cross-product dashboard (P4.5) + +Sync engine (P1.4) + │ + ├──→ Swift SDK (P3.1) + └──→ Kotlin SDK (P3.2) + +Auth UI kit (P2.2) + │ + └──→ Dashboard shell (P3.3) + +Telemetry (existing) + │ + └──→ Multi-product telemetry (P4.2) +``` + +--- + +## 7. Success Metrics + +| Metric | Baseline (Now) | After Phase 1-2 | After Phase 3-4 | Target | +| ------------------------------ | ----------------------- | ------------------- | --------------- | ---------- | +| Time to first `npm run dev` | 3–4 hours | 15 minutes | 5 minutes | < 10 min | +| Time to deployed MVP | 3–5 days | 1–2 days | 4–8 hours | < 8 hours | +| Lines of code per new product | ~3,000 | ~1,500 | ~500 | < 500 | +| Backend modules (manual code) | 150–250 lines each | 0 lines (generated) | 0 lines (YAML) | 0 lines | +| Native SDK integration | ~400 lines per platform | ~400 lines | ~20 lines | < 20 lines | +| Repeated files across products | ~15 files | ~5 files | ~0 files | 0 | +| Test coverage of platform | 1,141 tests | 1,300+ | 1,500+ | > 1,500 | + +--- + +## 8. Risk Register + +| Risk | Impact | Likelihood | Mitigation | +| ------------------------------------------------------ | ------ | ---------- | ---------------------------------------------------------------- | +| Over-abstraction makes platform hard to understand | High | Medium | Keep escape hatches; any generated code can be hand-modified | +| YAML declarative modules too limited for complex logic | Medium | Medium | Hybrid approach: YAML for CRUD, hand-written for complex modules | +| Native SDKs diverge from web package API | Medium | Low | Shared API design doc; test parity | +| CLI scaffolder templates go stale | High | High | Auto-test: CI runs scaffolder and builds result weekly | +| Manifest schema changes break existing products | High | Medium | Versioned schema with migration guide | +| Performance overhead of runtime YAML interpretation | Low | Low | Benchmark; fall back to code generation if needed | +| Too many packages to maintain | Medium | Medium | Regular dependency audit; merge underused packages | + +--- + +## Appendix: Quick Reference + +### All New Packages (by phase) + +| Phase | Package | Type | +| ----- | ----------------------------------------------- | ----------------- | +| 1 | Product manifest (in `@bytelyst/config`) | Extension | +| 1 | `@bytelyst/dashboard-components` | New package | +| 1 | `@bytelyst/sync` | New package | +| 1 | Module generator (in platform-service) | Script | +| 2 | `@bytelyst/create-app` | New package (CLI) | +| 2 | `@bytelyst/auth-ui` | New package | +| 2 | API route generator (in create-app) | Script | +| 2 | AGENTS.md generator (in create-app) | Script | +| 3 | `ByteLystSDK` (Swift) | New repo/package | +| 3 | `com.bytelyst.sdk` (Kotlin) | New repo/package | +| 3 | `@bytelyst/dashboard-shell` | New package | +| 3 | Declarative module loader (in platform-service) | Runtime | + +### Total Estimated Effort + +| Phase | Duration | Effort | +| --------- | ------------ | ----------- | +| Phase 1 | Weeks 1–2 | 9 days | +| Phase 2 | Weeks 3–6 | 14 days | +| Phase 3 | Weeks 7–12 | 30 days | +| Phase 4 | Weeks 13–16 | 17 days | +| **Total** | **16 weeks** | **70 days** |