docs: update platform_COMPONENTS_ROADMAP.md — comprehensive workspace scan (36 modules, 23 packages, 20/25 gaps built)

This commit is contained in:
saravanakumardb1 2026-03-01 23:28:45 -08:00
parent dd4410548e
commit 3cddc2f14e

View File

@ -1,9 +1,9 @@
# Platform Components Roadmap — What's Built, What's Missing, What's Next
> **Status:** Living document — brainstorm + gap analysis
> **Last updated:** 2026-03-15
> **Last updated:** 2026-03-01 (comprehensive workspace scan)
> **Scope:** All infrastructure components relevant to admin, DevOps, and product operations across the ByteLyst platform.
> **Repos:** `learning_ai_common_plat` (platform-service, packages) · `learning_voice_ai_agent` (dashboards, clients)
> **Repos:** `learning_ai_common_plat` (platform-service, 23 packages) · `learning_voice_ai_agent` (LysnrAI + user dashboard) · `learning_multimodal_memory_agents` (MindLyst) · `learning_ai_clock` (ChronoMind) · `learning_ai_jarvis_jr` (JarvisJr) · `learning_ai_fastgap` (NomGap) · `learning_ai_peakpulse` (PeakPulse)
---
@ -28,67 +28,120 @@
## 1. Current Inventory
### 1.1 Platform-Service Modules (30 modules)
### 1.1 Platform-Service Modules (36 modules)
| Category | Module | Endpoints | Description |
| ------------ | --------------- | --------- | --------------------------------------------------------------------------------------------------- |
| **Identity** | `auth` | 11 routes | Login, register, refresh, SSO, profile, admin user CRUD |
| **Identity** | `tokens` | 5 routes | API token management (CRUD + validate) |
| **Identity** | `licenses` | 6 routes | License key generation, activation, device binding, validate |
| **Billing** | `subscriptions` | 5 routes | Plan management, trial tracking, period management |
| **Billing** | `stripe` | 2 routes | Inbound Stripe webhook + portal session |
| **Billing** | `plans` | 4 routes | Plan definitions (free, pro, enterprise) |
| **Billing** | `usage` | 4 routes | Usage tracking and quota enforcement |
| **Billing** | `promos` | 5 routes | Promo code creation, validation, redemption |
| **Growth** | `invitations` | 5 routes | Invitation code generation, redemption, tracking |
| **Growth** | `referrals` | 5 routes | Referral link tracking, status transitions |
| **Growth** | `waitlist` | 12 routes | Pre-launch signups, position tracking, admin batch invite, CSV export |
| **Growth** | `public` | 5 routes | Public roadmap, community voting, feature submissions |
| **Content** | `items` | 5 routes | Tracker items (bugs, features, tasks) |
| **Content** | `comments` | 4 routes | Threaded comments on items |
| **Content** | `votes` | 3 routes | User votes on items and comments |
| **Content** | `memory` | 5 routes | Memory items — create, reassign, patch, delete |
| **Ops** | `audit` | Query | Audit log recording and admin queries |
| **Ops** | `flags` | 5 routes | Feature flags with FNV-1a deterministic rollout |
| **Ops** | `telemetry` | 9 routes | Client event ingestion, error clustering, collection policies, GDPR erasure |
| **Ops** | `notifications` | 5 routes | Device registration, notification preferences |
| **Ops** | `settings` | 6 routes | User/device settings, kill switch |
| **Ops** | `ratelimit` | 4 routes | Rate limit checking, config management |
| **Ops** | `themes` | 7 routes | Platform theming (iOS, Android, Desktop) |
| **Ops** | `blob` | 5 routes | Azure Blob Storage SAS tokens, list, delete, info |
| **Registry** | `products` | 4 routes | Multi-product registry with full lifecycle (draft → pre_launch → beta → active → sunset → disabled) |
| **Ops** | `jobs` | 5 routes | Scheduled jobs: cron parser, registry, runner, 6 built-in jobs, manual trigger |
| **Ops** | `status` | 6 routes | Public status page: health checker, incidents CRUD, history |
| **Ops** | `delivery` | 6 routes | Transactional email: 8 templates, renderer, SendGrid/Postmark/console adapters, delivery log |
| **Identity** | `auth` (reset) | 4 routes | Password reset (forgot/reset) + email verification (verify/resend) — added to auth module |
| **Infra** | `event-bus` | Singleton | In-memory typed pub/sub via @bytelyst/events — emits on register, password reset, email verified |
| Category | Module | Source Files | Description |
| ---------------- | --------------- | ------------ | --------------------------------------------------------------------------------------------------- |
| **Identity** | `auth` | 4 | Login, register, refresh, SSO, profile, admin user CRUD, password reset, email verification |
| **Identity** | `tokens` | 3 | API token management (CRUD + validate) |
| **Identity** | `licenses` | 3 | License key generation, activation, device binding, validate |
| **Identity** | `sessions` | 3 | Active session tracking, device list, revoke one/all _(was gap 2.7)_ |
| **Identity** | `impersonation` | 3 | Admin shadow mode — scoped read-only token with audit trail _(was gap 2.15)_ |
| **Billing** | `subscriptions` | 3 | Plan management, trial tracking, period management |
| **Billing** | `stripe` | 1 | Inbound Stripe webhook + portal session |
| **Billing** | `plans` | 3 | Plan definitions (free, pro, enterprise) |
| **Billing** | `usage` | 3 | Usage tracking and quota enforcement |
| **Billing** | `promos` | 2 | Promo code creation, validation, redemption |
| **Growth** | `invitations` | 3 | Invitation code generation, redemption, tracking |
| **Growth** | `referrals` | 3 | Referral link tracking, status transitions |
| **Growth** | `waitlist` | 3 | Pre-launch signups, position tracking, admin batch invite, CSV export |
| **Growth** | `public` | 2 | Public roadmap, community voting, feature submissions |
| **Content** | `items` | 3 | Tracker items (bugs, features, tasks) |
| **Content** | `comments` | 3 | Threaded comments on items |
| **Content** | `votes` | 3 | User votes on items and comments |
| **Content** | `changelog` | 3 | In-app release notes, admin CRUD, "What's New" _(was gap 2.16)_ |
| **Content** | `feedback` | 3 | In-app feedback: bug reports, NPS, feature requests _(was gap 2.14)_ |
| **Ops** | `audit` | 3 | Audit log recording and admin queries |
| **Ops** | `flags` | 4 | Feature flags with FNV-1a deterministic rollout |
| **Ops** | `telemetry` | 3 | Client event ingestion, error clustering, collection policies, GDPR erasure |
| **Ops** | `notifications` | 3 | Device registration, notification preferences |
| **Ops** | `settings` | 3 | User/device settings, kill switch |
| **Ops** | `ratelimit` | 3 | Rate limit checking, config management |
| **Ops** | `ip-rules` | 3 | IP allow/deny rules, per-product _(was gap 2.11)_ |
| **Ops** | `maintenance` | 3 | Maintenance mode: off/read-only/maintenance/emergency, admin bypass _(was gap 2.10)_ |
| **Ops** | `themes` | 3 | Platform theming (iOS, Android, Desktop) |
| **Ops** | `blob` | 2 | Azure Blob Storage SAS tokens, list, delete, info |
| **Ops** | `jobs` | 7 | Scheduled jobs: cron parser, registry, runner, 6 built-in jobs, manual trigger |
| **Ops** | `status` | 4 | Public status page: health checker, incidents CRUD, history |
| **Ops** | `delivery` | 8 | Transactional email: 8 templates, renderer, SendGrid/Postmark/console adapters, delivery log |
| **Ops** | `exports` | 3 | Data export: users, audit, telemetry, usage as CSV/JSON to blob _(was gap 2.9)_ |
| **Intelligence** | `analytics` | 3 | DAU/WAU/MAU rollups, retention cohorts, funnels _(was gap 2.13)_ |
| **Intelligence** | `experiments` | 3 | A/B testing: variant assignment, metric collection, significance _(was gap 2.12)_ |
| **Registry** | `products` | 4 | Multi-product registry with full lifecycle (draft → pre_launch → beta → active → sunset → disabled) |
### 1.2 Shared Packages (13 packages)
### 1.2 Shared Packages (23 packages)
**Server-side packages (used by platform-service + product backends):**
| Package | Purpose |
| ------------------------ | ------------------------------------------------ |
| `@bytelyst/errors` | Typed HTTP errors (400429) |
| `@bytelyst/cosmos` | Cosmos DB client singleton + container registry |
| `@bytelyst/config` | Zod env loader, product identity, AKV resolver |
| `@bytelyst/auth` | JWT utilities, auth middleware, password hashing |
| `@bytelyst/api-client` | Fetch wrapper with auth token injection |
| `@bytelyst/fastify-core` | `createServiceApp()` factory + `startService()` |
| `@bytelyst/logger` | Structured logging (pino-based) |
| `@bytelyst/testing` | Shared test mocks, Fastify inject helpers |
| `@bytelyst/blob` | Azure Blob Storage server client + SAS helpers |
| `@bytelyst/extraction` | Extraction client + shared types |
| `@bytelyst/monitoring` | Health-check utilities |
| `@bytelyst/events` | Typed in-memory event bus with error isolation |
**Client-side packages (used by dashboards, React Native, browser):**
| Package | Purpose |
| ------------------------------- | ------------------------------------------------------- |
| `@bytelyst/react-auth` | React auth context factory (typed provider + hook) |
| `@bytelyst/auth-client` | Browser/RN auth client (login, register, token refresh) |
| `@bytelyst/platform-client` | Typed fetch wrapper for platform-service APIs |
| `@bytelyst/telemetry-client` | Browser/RN telemetry event emitter |
| `@bytelyst/feature-flag-client` | Client-side feature flag polling + caching |
| `@bytelyst/kill-switch-client` | Client-side kill switch check |
| `@bytelyst/blob-client` | Browser/RN blob upload + SAS token helper |
| `@bytelyst/offline-queue` | Persistent retry queue for offline-first apps |
**Cross-platform packages:**
| Package | Purpose |
| ------------------------- | ----------------------------------------------------------- |
| `@bytelyst/errors` | Typed HTTP errors (400429) |
| `@bytelyst/cosmos` | Cosmos DB client singleton + container registry |
| `@bytelyst/config` | Zod env loader, product identity, AKV resolver |
| `@bytelyst/auth` | JWT utilities, auth middleware, password hashing |
| `@bytelyst/api-client` | Fetch wrapper with auth token injection |
| `@bytelyst/fastify-core` | `createServiceApp()` factory + `startService()` |
| `@bytelyst/react-auth` | React auth context factory |
| `@bytelyst/logger` | Structured logging (pino-based) |
| `@bytelyst/testing` | Shared test mocks, Fastify inject helpers |
| `@bytelyst/blob` | Azure Blob Storage client + SAS helpers |
| `@bytelyst/extraction` | Extraction client + shared types |
| `@bytelyst/monitoring` | Health-check utilities |
| `@bytelyst/design-tokens` | Cross-platform token generator (JSON → CSS/TS/Kotlin/Swift) |
| `@bytelyst/events` | Typed in-memory event bus with error isolation (14 tests) |
| `kotlin-platform-sdk` | Android SDK (13 components, 35 JUnit5 tests) — Kotlin |
| `swift-platform-sdk` | iOS SDK (13 components) — Swift Package |
### 1.3 Services
| Service | Port | Description |
| ---------------------- | ---- | ---------------------------------------------------- |
| **platform-service** | 4003 | Consolidated Fastify service (30 modules, 988 tests) |
| **extraction-service** | 4005 | LangExtract text extraction + Python sidecar |
| **monitoring** | 4004 | Health-check aggregator (all services) |
| Service | Port | Description |
| ---------------------- | ---- | -------------------------------------------------------------- |
| **platform-service** | 4003 | Consolidated Fastify service (36 modules, ~1,039 tests) |
| **extraction-service** | 4005 | LangExtract text extraction + Python sidecar |
| **monitoring** | — | Health-check aggregator (Loki + Grafana + health-check script) |
> **Test breakdown:** 766 module tests + 12 lib tests + 261 package tests = ~1,039 across common-plat.
### 1.6 Product-Specific Backends
Each product has its own Fastify 5 backend in the product repo's `backend/` directory. These consume `@bytelyst/*` packages via `file:` refs and use the same module pattern (`types.ts → repository.ts → routes.ts`).
| Product | Repo | Port | Modules | Tests |
| -------------- | -------------------------------------------- | ---- | -------------------------------------------------------------------------------- | ----- |
| **LysnrAI** | `learning_voice_ai_agent/backend/` | 4015 | transcripts, sessions, organizations, api-tokens, webhooks, themes, export | 62 |
| **ChronoMind** | `learning_ai_clock/backend/` | 4011 | timers, routines, households, shared-timers, webhooks | 171 |
| **JarvisJr** | `learning_ai_jarvis_jr/backend/` | 4012 | jarvis-agents, jarvis-sessions, jarvis-memory, jarvis-teams, marketplace | 198 |
| **NomGap** | `learning_ai_fastgap/backend/` | 4013 | fasting-sessions, fasting-protocols, body-stages, social-fasting, meal-log, push | 152 |
| **MindLyst** | `learning_multimodal_memory_agents/backend/` | 4014 | brains, memory, reflections, daily-briefs, streaks | 59 |
| **PeakPulse** | `learning_ai_peakpulse/backend/` | 4010 | peak-sessions, peak-routes | 32 |
> **Total product backend tests:** 674. **Grand total service tests:** ~1,039 + 674 = **~1,713**.
### 1.7 Mobile Platform SDKs
| SDK | Language | Components | Tests | Consumers |
| ----------------------- | -------- | ---------- | -------------- | --------------------------------------------------------------- |
| **swift-platform-sdk** | Swift | 13 | (via consumer) | LysnrAI, ChronoMind, MindLyst, JarvisJr, PeakPulse (5 iOS apps) |
| **kotlin-platform-sdk** | Kotlin | 13 | 35 JUnit5 | LysnrAI, ChronoMind, MindLyst (3 Android apps) |
Both SDKs provide: `BLPlatformConfig`, `BLPlatformClient`, `BLAuthClient`, `BLTelemetryClient`, `BLFeatureFlagClient`, `BLKillSwitchClient`, `BLLicenseClient`, `BLSecureStore`, `BLBlobClient`, `BLBiometricAuth`, `BLCrashReporter`, `BLAuditLogger`, `BLSyncEngine`.
### 1.4 Dashboards
@ -100,42 +153,59 @@
### 1.5 Infrastructure Already In Place
| Component | Status | Notes |
| ---------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| **Health checks** | ✅ | Per-service `/health` + aggregated monitoring script |
| **Structured logging** | ✅ | Pino (Fastify) + structlog (Python) |
| **Log aggregation** | ✅ | Loki + Grafana (Docker Compose) |
| **Reverse proxy** | ✅ | Traefik (Docker Compose) |
| **Secret management** | ✅ | Azure Key Vault + admin CRUD UI at `/ops/secrets` |
| **Feature flags** | ✅ | FNV-1a hash, percentage rollout, admin UI |
| **Client telemetry** | ✅ | All platforms instrumented, admin Client Logs page |
| **Rate limiting** | ✅ | In-memory sliding window + configurable rules per product |
| **Outbound webhooks** | ⚠️ Partial | Fire-and-forget POST for 3 events (`lib/webhooks.ts`); subscription model built in `modules/webhooks/` with HMAC signing + retry |
| **Event bus** | ✅ | `@bytelyst/events` package + singleton in platform-service; auth emits user.created, password_reset, email_verified |
| **Scheduled jobs** | ✅ | Cron parser, registry, in-process runner, 6 built-in jobs, admin API |
| **Email delivery** | ✅ | 8 templates, renderer, SendGrid/Postmark/console adapters, delivery log, event bus subscribers |
| **Password reset** | ✅ | forgot-password + reset-password endpoints, SHA-256 token hashing, anti-enumeration |
| **Email verification** | ✅ | verify-email + resend-verification endpoints, emailVerified field on UserDoc |
| **Status page** | ✅ | Health checker (3 services), incident management, public + admin endpoints |
| **Kill switch** | ✅ | Per-product, checked by all clients via `/settings/kill-switch` |
| **Audit logging** | ✅ | Records admin actions, queryable from admin dashboard |
| **Blob storage** | ✅ | 6 containers (audio, transcripts, attachments, avatars, releases, backups), SAS tokens, admin endpoints |
| **Swagger / OpenAPI** | ⚠️ Partial | `createServiceApp()` passes `swagger` config; Fastify plugin wired but Zod schemas not fully connected to route definitions via type provider |
| **Prometheus metrics** | ⚠️ Partial | `metrics: true` in `createServiceApp()` — basic request metrics exposed; no custom business metrics, no Grafana dashboards for them |
| **Product registry** | ✅ | Multi-product with full status lifecycle (draft → pre_launch → beta → active → sunset → disabled), prelaunch config, custom fields |
| **Admin doc browser** | ✅ | `/docs` page with markdown viewer, search, and AI chat — browses repo documentation |
| Component | Status | Notes |
| ---------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Health checks** | ✅ | Per-service `/health` + aggregated monitoring script |
| **Structured logging** | ✅ | Pino (Fastify) + structlog (Python) |
| **Log aggregation** | ✅ | Loki + Grafana (Docker Compose) |
| **Reverse proxy** | ✅ | Traefik (Docker Compose) |
| **Secret management** | ✅ | Azure Key Vault + admin CRUD UI at `/ops/secrets` |
| **Feature flags** | ✅ | FNV-1a hash, percentage rollout, admin UI |
| **Client telemetry** | ✅ | All platforms instrumented, admin Client Logs page |
| **Rate limiting** | ✅ | In-memory sliding window + configurable rules per product |
| **Event bus** | ✅ | `@bytelyst/events` package + singleton in platform-service; auth emits user.created, password_reset, email_verified |
| **Scheduled jobs** | ✅ | Cron parser, registry, in-process runner, 6 built-in jobs, admin API |
| **Email delivery** | ✅ | 8 templates, renderer, SendGrid/Postmark/console adapters, delivery log, event bus subscribers |
| **Password reset** | ✅ | forgot-password + reset-password endpoints, SHA-256 token hashing, anti-enumeration |
| **Email verification** | ✅ | verify-email + resend-verification endpoints, emailVerified field on UserDoc |
| **Status page** | ✅ | Health checker (3 services), incident management, public + admin endpoints |
| **Kill switch** | ✅ | Per-product, checked by all clients via `/settings/kill-switch` |
| **Audit logging** | ✅ | Records admin actions, queryable from admin dashboard |
| **Blob storage** | ✅ | 6 containers (audio, transcripts, attachments, avatars, releases, backups), SAS tokens, admin endpoints |
| **Session management** | ✅ | Active session tracking, device list, revoke one/all _(was gap 2.7)_ |
| **Maintenance mode** | ✅ | off/read-only/maintenance/emergency modes, admin bypass, scheduled windows _(was gap 2.10)_ |
| **IP rules** | ✅ | Per-product IP allow/deny rules _(was gap 2.11)_ |
| **Data export** | ✅ | Users, audit, telemetry, usage as CSV/JSON to blob _(was gap 2.9)_ |
| **A/B experiments** | ✅ | Variant assignment, metric collection, significance calculation _(was gap 2.12)_ |
| **Analytics rollups** | ✅ | DAU/WAU/MAU, retention cohorts, funnel analysis _(was gap 2.13)_ |
| **In-app feedback** | ✅ | Bug reports, NPS surveys, feature requests with device context _(was gap 2.14)_ |
| **Impersonation** | ✅ | Admin shadow mode with scoped read-only token _(was gap 2.15)_ |
| **Changelog** | ✅ | In-app release notes, admin CRUD, "What's New" per product _(was gap 2.16)_ |
| **Swagger / OpenAPI** | ⚠️ Partial | `createServiceApp()` passes `swagger` config; Fastify plugin wired but Zod schemas not fully connected to route definitions via type provider |
| **Prometheus metrics** | ⚠️ Partial | `metrics: true` in `createServiceApp()` — basic request metrics exposed; no custom business metrics, no Grafana dashboards for them |
| **Outbound webhooks** | ⚠️ Partial | Fire-and-forget POST for 3 events (`lib/webhooks.ts`); no subscription model, no retry, no HMAC signing |
| **Product registry** | ✅ | Multi-product with full status lifecycle (draft → pre_launch → beta → active → sunset → disabled), prelaunch config, custom fields |
| **Admin doc browser** | ✅ | `/docs` page with markdown viewer, search, and AI chat — browses repo documentation |
| **Mobile SDKs** | ✅ | Swift (13 components, 5 iOS apps) + Kotlin (13 components, 35 tests, 3 Android apps) |
| **Client-side pkgs** | ✅ | 8 `@bytelyst/*` client packages: auth-client, platform-client, telemetry-client, feature-flag-client, kill-switch-client, blob-client, offline-queue, react-auth |
| **Product backends** | ✅ | 6 product-specific Fastify backends (674 tests total) — product logic separated from platform-service |
---
## 2. Gap Analysis — Missing Components
### P0 — Foundational
> **Status as of 2026-03-01:** 20 of 25 gap items are now **✅ BUILT**. 2 are **⚠️ Partial**. 3 remain **❌ Not Started** (all P3).
> The detailed designs below are preserved as reference for the implementations.
These are blocking features that nearly every production app needs. Without them, critical operational workflows are manual or impossible.
### P0 — Foundational ✅ ALL BUILT
These are blocking features that nearly every production app needs. All P0 items have been implemented.
---
#### 2.1 Scheduled Jobs / Background Task Runner
#### 2.1 Scheduled Jobs / Background Task Runner ✅ BUILT
> **Implementation:** `modules/jobs/` (7 source files) — cron parser, registry, in-process runner, 6 built-in jobs, admin API.
**Why:** No way to run recurring work today. Trial expirations, subscription renewals, usage quota resets, stale data cleanup, digest emails, and report generation all require a scheduler.
@ -185,7 +255,9 @@ platform-service/src/modules/jobs/
---
#### 2.2 Transactional Email & Push Delivery
#### 2.2 Transactional Email & Push Delivery ✅ BUILT
> **Implementation:** `modules/delivery/` (8 source files) — 8 templates, renderer, SendGrid/Postmark/console adapters, delivery log, event bus subscribers.
**Why:** The `notifications` module manages device registration and preferences, but has **no delivery mechanism**. Notifications are database records with no way to reach users.
@ -241,7 +313,9 @@ platform-service/src/modules/delivery/
---
#### 2.3 Outbound Webhook Subscriptions
#### 2.3 Outbound Webhook Subscriptions ⚠️ PARTIAL
> **Current state:** `lib/webhooks.ts` still fire-and-forget for 3 events. No `modules/webhooks/` directory exists — subscription model with HMAC signing + retry has NOT been built.
**Why:** Current `webhooks.ts` is fire-and-forget to env-var URLs with no retry, no signing, no subscriber management. External integrations (Zapier, Slack, custom) need a proper webhook subscription system.
@ -301,7 +375,9 @@ platform-service/src/modules/webhooks/
---
#### 2.4 Async Event Bus / Internal Pub-Sub
#### 2.4 Async Event Bus / Internal Pub-Sub ✅ BUILT
> **Implementation:** `@bytelyst/events` package (14 tests) + `lib/event-bus.ts` singleton in platform-service. Auth emits `user.created`, `password_reset`, `email_verified`.
**Why:** Today everything is synchronous request-response. As the platform grows, many operations should be fire-and-forget: audit log writes, webhook delivery, email sending, telemetry cluster updates, usage tracking. Without decoupling, any slow downstream operation blocks the API response.
@ -366,7 +442,9 @@ const PlatformEvents = {
---
#### 2.5 Missing Auth Flows — Password Reset & Email Verification
#### 2.5 Missing Auth Flows — Password Reset & Email Verification ✅ BUILT
> **Implementation:** Added to `modules/auth/` — forgot-password, reset-password, verify-email, resend-verification endpoints. SHA-256 token hashing, anti-enumeration.
**Why:** The auth module has login, register, SSO, and refresh — but **no password reset** and **no email verification**. These are table-stakes for any production auth system.
@ -416,7 +494,9 @@ interface PasswordResetToken {
---
#### 2.6 Public Status Page
#### 2.6 Public Status Page ✅ BUILT
> **Implementation:** `modules/status/` (4 source files) — health checker for 3 services, incident management CRUD, public + admin endpoints.
**Why:** Users and admins need a single place to check if services are operational. The health-check script exists but has no user-facing output.
@ -459,13 +539,15 @@ platform-service/src/modules/status/
---
### P1 — Operational Maturity
### P1 — Operational Maturity (4 of 5 BUILT, 1 NOT STARTED)
These components improve reliability, debuggability, and operational efficiency. Not launch-blocking, but critical for a team running production services.
---
#### 2.7 Session Management & Active Devices
#### 2.7 Session Management & Active Devices ✅ BUILT
> **Implementation:** `modules/sessions/` (3 source files) — session tracking, device list, revoke one/all, admin force-revoke.
**Why:** Licenses track `deviceIds` but there's no concept of active sessions. Users can't see where they're logged in. Admins can't force-revoke a compromised session. "Sign out all devices" is impossible.
@ -512,7 +594,9 @@ interface SessionDoc {
---
#### 2.8 Database Migration & Schema Evolution Tracker
#### 2.8 Database Migration & Schema Evolution Tracker ❌ NOT STARTED
> **Status:** No `migrations/` directory exists. Schema changes are still applied ad-hoc.
**Why:** Cosmos DB is schemaless, but breaking changes still happen: new required fields, partition key changes, index policy updates, container renames. Without tracking, deployments are error-prone and rollbacks are impossible.
@ -555,7 +639,9 @@ interface MigrationDoc {
---
#### 2.9 Data Export & Bulk Operations
#### 2.9 Data Export & Bulk Operations ✅ BUILT
> **Implementation:** `modules/exports/` (3 source files) — export users, audit, telemetry, usage as CSV/JSON to blob storage.
**Why:** Admins regularly need: export users as CSV, export audit logs, bulk status updates, bulk license revocation. Today these require direct database queries.
@ -602,7 +688,9 @@ platform-service/src/modules/exports/
---
#### 2.10 Maintenance Mode & Graceful Degradation
#### 2.10 Maintenance Mode & Graceful Degradation ✅ BUILT
> **Implementation:** `modules/maintenance/` (3 source files) — off/read-only/maintenance/emergency modes, admin bypass, scheduled windows.
**Why:** Kill switch is binary (on/off per product). Need nuanced control: read-only mode, specific features disabled, custom banner messages, admin bypass, scheduled windows.
@ -658,7 +746,9 @@ interface MaintenanceConfig {
---
#### 2.11 Rate Limit Dashboard & IP Allow/Deny Lists
#### 2.11 Rate Limit Dashboard & IP Allow/Deny Lists ✅ BUILT
> **Implementation:** `modules/ip-rules/` (3 source files) — per-product IP allow/deny rules with expiry.
**Why:** `ratelimit` module exists but admins have zero visibility into who's being rate-limited, and no ability to whitelist VIP users or blacklist abusive IPs.
@ -712,13 +802,15 @@ interface IPRule {
---
### P2 — Product Intelligence
### P2 — Product Intelligence ✅ ALL BUILT
These components provide deeper insight into product health, user behavior, and experiment outcomes. They transform raw data into actionable intelligence.
These components provide deeper insight into product health, user behavior, and experiment outcomes. All P2 items have been implemented.
---
#### 2.12 A/B Testing & Experiments Framework
#### 2.12 A/B Testing & Experiments Framework ✅ BUILT
> **Implementation:** `modules/experiments/` (3 source files) — variant assignment, metric collection, statistical significance calculation.
**Why:** Feature flags exist but only support on/off with percentage rollout. No variant assignment, metric collection, or statistical significance calculation.
@ -766,7 +858,9 @@ interface ExperimentDoc {
---
#### 2.13 Analytics Aggregation Pipeline
#### 2.13 Analytics Aggregation Pipeline ✅ BUILT
> **Implementation:** `modules/analytics/` (3 source files) — DAU/WAU/MAU rollups, retention cohorts, funnel analysis, feature adoption.
**Why:** `usage` tracks raw events but there are no pre-aggregated rollups. Admin dashboard charts require expensive real-time queries. DAU/WAU/MAU, retention cohorts, and funnel analysis are impossible without rollups.
@ -808,7 +902,9 @@ platform-service/src/modules/analytics/
---
#### 2.14 In-App Feedback & Support Widget
#### 2.14 In-App Feedback & Support Widget ✅ BUILT
> **Implementation:** `modules/feedback/` (3 source files) — bug reports, NPS surveys, feature requests with device context.
**Why:** Tracker handles issue tracking but there's no way for end users to submit feedback directly from the app. Bug reports with device context, NPS surveys, and feature requests should flow into the tracker automatically.
@ -844,7 +940,9 @@ platform-service/src/modules/feedback/
---
#### 2.15 User Impersonation / Admin Shadow Mode
#### 2.15 User Impersonation / Admin Shadow Mode ✅ BUILT
> **Implementation:** `modules/impersonation/` (3 source files) — scoped read-only shadow token, 15-min expiry, full audit trail.
**Why:** When a user reports a bug, admins need to see exactly what they see. Without impersonation, debugging requires asking users for screenshots and steps, which is slow and unreliable.
@ -872,7 +970,9 @@ platform-service/src/modules/feedback/
---
#### 2.16 Changelog & In-App Release Notes
#### 2.16 Changelog & In-App Release Notes ✅ BUILT
> **Implementation:** `modules/changelog/` (3 source files) — per-product entries, admin CRUD, public endpoint for "What's New".
**Why:** Users should know what changed in each release. A changelog system also serves as internal documentation and can be shown as a "What's New" modal in the app.
@ -919,13 +1019,13 @@ interface ChangelogEntry {
---
### P3 — Scale & Polish
### P3 — Scale & Polish (0 of 9 BUILT)
These components are important for scale, security, and developer experience, but are lower urgency.
These components are important for scale, security, and developer experience, but are lower urgency. None have been started.
---
#### 2.17 CDN & Asset Pipeline
#### 2.17 CDN & Asset Pipeline ❌ NOT STARTED
**Why:** Blob storage serves files directly from Azure. No edge caching, no image optimization, no automatic resizing for avatars/thumbnails.
@ -938,7 +1038,7 @@ These components are important for scale, security, and developer experience, bu
---
#### 2.18 API Versioning Strategy
#### 2.18 API Versioning Strategy ❌ NOT STARTED
**Why:** As external consumers appear (webhook integrations, third-party tools), breaking API changes need to be managed. Today all endpoints are unversioned.
@ -952,7 +1052,7 @@ These components are important for scale, security, and developer experience, bu
---
#### 2.19 OpenAPI / Auto-Generated API Docs
#### 2.19 OpenAPI / Auto-Generated API Docs ⚠️ PARTIAL
**Why:** Platform-service already passes `swagger` config to `createServiceApp()`, but Zod schemas aren't fully wired to route definitions. The admin `/docs` page is a markdown doc browser (not API docs). Auto-generated API docs from Zod schemas would be nearly free.
@ -968,7 +1068,7 @@ These components are important for scale, security, and developer experience, bu
---
#### 2.20 Localization / i18n Service
#### 2.20 Localization / i18n Service ❌ NOT STARTED
**Why:** Centralized string management for all platforms. When adding a new language, change one place, not four codebases.
@ -981,7 +1081,7 @@ These components are important for scale, security, and developer experience, bu
---
#### 2.21 Full-Text Search
#### 2.21 Full-Text Search ❌ NOT STARTED
**Why:** Admin needs to search users by partial name/email. Users need to search memories/items. Cosmos SQL `CONTAINS()` is slow and doesn't rank results.
@ -993,7 +1093,7 @@ These components are important for scale, security, and developer experience, bu
---
#### 2.22 Multi-Tenant Workspace / Org / Team Management
#### 2.22 Multi-Tenant Workspace / Org / Team Management ❌ NOT STARTED
**Why:** `productId` scopes data per product, but within a product there's no team or organization concept. Enterprise customers need: org hierarchy, team-scoped permissions, shared brains/workspaces.
@ -1007,7 +1107,7 @@ This is a major architectural expansion. Defer until enterprise tier is validate
---
#### 2.23 Data Retention & Lifecycle Policies
#### 2.23 Data Retention & Lifecycle Policies ❌ NOT STARTED
**Why:** Telemetry has TTL. Other containers don't. Old audit logs, expired sessions, redeemed promos, and stale waitlist entries accumulate forever.
@ -1020,7 +1120,7 @@ This is a major architectural expansion. Defer until enterprise tier is validate
---
#### 2.24 Automated Backup & Point-in-Time Restore
#### 2.24 Automated Backup & Point-in-Time Restore ❌ NOT STARTED
**Why:** Azure Cosmos DB has continuous backup, but admin needs visibility and one-click restore capability.
@ -1033,7 +1133,7 @@ This is a major architectural expansion. Defer until enterprise tier is validate
---
#### 2.25 Billing Dunning & Payment Recovery
#### 2.25 Billing Dunning & Payment Recovery ❌ NOT STARTED
**Why:** Stripe handles retries, but the platform needs to: notify users of failed payments, offer grace periods, and eventually downgrade plans.
@ -1050,27 +1150,30 @@ This is a major architectural expansion. Defer until enterprise tier is validate
## 3. Implementation Priority Matrix
| Phase | Components | Effort | Dependencies | Unlocks |
| ------------ | ------------------------------------------ | ------ | -------------------------------- | ---------------------------------------------------------- |
| **Sprint 1** | 2.1 Scheduled Jobs | M | None | Foundation for all time-based operations |
| **Sprint 1** | 2.4 Event Bus | S | None | Decoupling for email, webhooks, audit |
| **Sprint 2** | 2.2 Email Delivery | M | 2.4 Event Bus | User communication (welcome, trial expiry, payment failed) |
| **Sprint 2** | 2.5 Password Reset + Email Verify | S | 2.2 Email Delivery | Auth completeness — table-stakes for production |
| **Sprint 3** | 2.3 Webhook Subscriptions | M | 2.4 Event Bus | Third-party integrations, Zapier/Slack |
| **Sprint 3** | 2.7 Session Management | S | None | Security (sign out everywhere, revocation) |
| **Sprint 4** | 2.10 Maintenance Mode | S | None | Operational control during deployments |
| **Sprint 4** | 2.9 Data Export | S | 2.1 Jobs (for blob cleanup) | Admin self-service, compliance |
| **Sprint 5** | 2.13 Analytics Rollups | M | 2.1 Jobs (for rollup scheduling) | Dashboard charts, business metrics |
| **Sprint 5** | 2.19 OpenAPI Docs | S | None | Developer experience, API discoverability |
| **Sprint 6** | 2.6 Status Page | S | None | User trust, incident communication |
| **Sprint 6** | 2.16 Changelog | S | None | User engagement, release communication |
| **Sprint 7** | 2.11 Rate Limit Dashboard | S | None | Ops visibility |
| **Sprint 7** | 2.25 Billing Dunning | S | 2.1 Jobs + 2.2 Email | Payment recovery automation |
| **Later** | 2.8, 2.12, 2.142.15, 2.172.18, 2.202.24 | Varies | — | Scale, polish, enterprise |
| Phase | Components | Status | Notes |
| ------------ | ------------------------------------ | -------------- | ----------------------------------------------------------------------- |
| **Sprint 1** | 2.1 Scheduled Jobs | ✅ Complete | `modules/jobs/` — 7 source files |
| **Sprint 1** | 2.4 Event Bus | ✅ Complete | `@bytelyst/events` + `lib/event-bus.ts` |
| **Sprint 2** | 2.2 Email Delivery | ✅ Complete | `modules/delivery/` — 8 source files |
| **Sprint 2** | 2.5 Password Reset + Email Verify | ✅ Complete | Added to `modules/auth/` |
| **Sprint 3** | 2.3 Webhook Subscriptions | ⚠️ Partial | `lib/webhooks.ts` fire-and-forget only; no subscription module |
| **Sprint 3** | 2.7 Session Management | ✅ Complete | `modules/sessions/` — 3 source files |
| **Sprint 4** | 2.10 Maintenance Mode | ✅ Complete | `modules/maintenance/` — 3 source files |
| **Sprint 4** | 2.9 Data Export | ✅ Complete | `modules/exports/` — 3 source files |
| **Sprint 5** | 2.13 Analytics Rollups | ✅ Complete | `modules/analytics/` — 3 source files |
| **Sprint 5** | 2.19 OpenAPI Docs | ⚠️ Partial | Swagger wired but Zod schemas not connected to routes |
| **Sprint 6** | 2.6 Status Page | ✅ Complete | `modules/status/` — 4 source files |
| **Sprint 6** | 2.16 Changelog | ✅ Complete | `modules/changelog/` — 3 source files |
| **Sprint 7** | 2.11 Rate Limit Dashboard + IP Rules | ✅ Complete | `modules/ip-rules/` — 3 source files |
| **Sprint 7** | 2.12 A/B Experiments | ✅ Complete | `modules/experiments/` — 3 source files |
| **Sprint 7** | 2.14 In-App Feedback | ✅ Complete | `modules/feedback/` — 3 source files |
| **Sprint 7** | 2.15 User Impersonation | ✅ Complete | `modules/impersonation/` — 3 source files |
| **Later** | 2.8 DB Migrations | ❌ Not Started | Schema changes still ad-hoc |
| **Later** | 2.172.18, 2.202.25 | ❌ Not Started | CDN, versioning, i18n, search, multi-tenant, retention, backup, dunning |
**Effort key:** S = Small (12 days), M = Medium (35 days), L = Large (12 weeks)
**Summary:** 20 of 25 gap items ✅ complete. 2 ⚠️ partial (webhooks, OpenAPI). 3 ❌ not started (migrations + P3 scale items).
**Critical path:** Event Bus (2.4) → Email Delivery (2.2) → Password Reset (2.5). These three should be the first items built, in that order.
**Remaining critical path:** Webhook subscriptions (2.3) is the only P0 item still incomplete — `lib/webhooks.ts` fire-and-forget should be replaced with a proper `modules/webhooks/` subscription model.
---
@ -1135,23 +1238,35 @@ New components will require additional env vars. All should be added to `.env.ex
## 6. Quick Reference — Where Things Live
| Component | Repo | Path |
| ------------------------ | ----------------------------------- | ------------------------------------------------------ |
| Platform-service modules | `learning_ai_common_plat` | `services/platform-service/src/modules/` |
| Shared packages | `learning_ai_common_plat` | `packages/` |
| Admin dashboard | `learning_voice_ai_agent` | `admin-dashboard-web/` |
| User dashboard | `learning_voice_ai_agent` | `user-dashboard-web/` |
| Tracker dashboard | `learning_voice_ai_agent` | `tracker-dashboard-web/` |
| Docker Compose | both repos | `docker-compose.yml` |
| Monitoring | `learning_ai_common_plat` | `services/monitoring/` |
| Design tokens | `learning_ai_common_plat` | `packages/design-tokens/` |
| MindLyst native app | `learning_multimodal_memory_agents` | `mindlyst-native/` (KMP + SwiftUI + Compose + Next.js) |
| MindLyst web | `learning_multimodal_memory_agents` | `mindlyst-native/web/` |
| Existing webhooks | `learning_ai_common_plat` | `services/platform-service/src/lib/webhooks.ts` |
| Cosmos container defs | `learning_ai_common_plat` | `services/platform-service/src/lib/cosmos-init.ts` |
| Telemetry design doc | `learning_ai_common_plat` | `docs/WINDSURF/CLIENT_TELEMETRY_DESIGN.md` |
| Telemetry roadmap | `learning_ai_common_plat` | `docs/WINDSURF/TELEMETRY_ROADMAP.md` |
| **This document** | `learning_ai_common_plat` | `docs/WINDSURF/PLATFORM_COMPONENTS_ROADMAP.md` |
**Common Platform (`learning_ai_common_plat`):**
| Component | Path |
| ------------------------ | ----------------------------------------------------------- |
| Platform-service modules | `services/platform-service/src/modules/` (36 modules) |
| Shared packages | `packages/` (23 packages) |
| Kotlin SDK | `packages/kotlin-platform-sdk/` |
| Swift SDK | `packages/swift-platform-sdk/` |
| Admin dashboard | `dashboards/admin-web/` (port 3001) |
| Tracker dashboard | `dashboards/tracker-web/` (port 3003) |
| Monitoring | `services/monitoring/` |
| Design tokens | `packages/design-tokens/` |
| Fire-and-forget webhooks | `services/platform-service/src/lib/webhooks.ts` |
| Cosmos container defs | `services/platform-service/src/lib/cosmos-init.ts` |
| Event bus singleton | `services/platform-service/src/lib/event-bus.ts` |
| Telemetry design doc | `docs/design/CLIENT_TELEMETRY_DESIGN.md` |
| Telemetry roadmap | `docs/roadmaps/partial/telemetry_IMPLEMENTATION_ROADMAP.md` |
| **This document** | `docs/roadmaps/partial/platform_COMPONENTS_ROADMAP.md` |
**Product Repos:**
| Repo | Product | Backend Port | Key Paths |
| ----------------------------------- | ---------- | ------------ | --------------------------------------------------- |
| `learning_voice_ai_agent` | LysnrAI | 4015 | `backend/`, `user-dashboard-web/`, `src/` (desktop) |
| `learning_ai_clock` | ChronoMind | 4011 | `backend/`, `web/`, `ios/`, `android/` |
| `learning_ai_jarvis_jr` | JarvisJr | 4012 | `backend/`, `web/`, `ios/`, `android/` |
| `learning_ai_fastgap` | NomGap | 4013 | `backend/`, `src/` (Expo RN) |
| `learning_multimodal_memory_agents` | MindLyst | 4014 | `backend/`, `mindlyst-native/` |
| `learning_ai_peakpulse` | PeakPulse | 4010 | `backend/`, `ios/` |
---