# 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 <name> --fields "<field:type,...>" --partition <key>`
- [ ] 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 `<module>.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<SyncResult>
  engine.fullSync() → Promise<SyncResult>
  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):
  - [ ] `<LoginPage productName logo theme ssoProviders onSuccess />`
  - [ ] `<RegisterPage productName logo theme onSuccess />`
  - [ ] `<ForgotPasswordPage productName logo theme />`
  - [ ] `<ResetPasswordPage productName logo theme />`
  - [ ] `<VerifyEmailPage productName logo theme />`
  - [ ] `<OnboardingShell steps currentStep onNext onBack onComplete />`
- [ ] 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:**

- `<LoginPage>` 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/<name>/route.ts` with GET (list) + POST (create)
- [ ] Generate `src/app/api/<name>/[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 `<!-- CUSTOM -->` 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 `<DashboardShell>` 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:**

- `<DashboardShell navItems={[...]} features={{ billing: true }}>` 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** |
