# 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** |