# Platform Components Roadmap — What's Built, What's Missing, What's Next

> **Status:** Living document — brainstorm + gap analysis  
> **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, 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)

---

## Table of Contents

1. [Current Inventory](#1-current-inventory)
2. [Gap Analysis — Missing Components](#2-gap-analysis--missing-components)
   - [P0 — Foundational](#p0--foundational)
   - [P1 — Operational Maturity](#p1--operational-maturity)
   - [P2 — Product Intelligence](#p2--product-intelligence)
   - [P3 — Scale & Polish](#p3--scale--polish)
3. [Implementation Priority Matrix](#3-implementation-priority-matrix)
4. [New Cosmos Containers & Cost Impact](#4-new-cosmos-containers--cost-impact)
5. [New Environment Variables](#5-new-environment-variables)
6. [Quick Reference — Where Things Live](#6-quick-reference--where-things-live)

- [Appendix A: Risks & Open Questions](#appendix-a-risks--open-questions)
- [Appendix B: Component Dependency Graph](#appendix-b-component-dependency-graph)
- [Appendix C: Review Findings](#appendix-c-review-findings)

---

## 1. Current Inventory

### 1.1 Platform-Service Modules (36 modules)

| 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 (23 packages)

**Server-side packages (used by platform-service + product backends):**

| Package                  | Purpose                                          |
| ------------------------ | ------------------------------------------------ |
| `@bytelyst/errors`       | Typed HTTP errors (400–429)                      |
| `@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/design-tokens` | Cross-platform token generator (JSON → CSS/TS/Kotlin/Swift) |
| `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 (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

| Dashboard                 | Port | Pages                                                            |
| ------------------------- | ---- | ---------------------------------------------------------------- |
| **admin-dashboard-web**   | 3001 | ~25 pages — users, billing, flags, ops, telemetry, secrets, etc. |
| **user-dashboard-web**    | 3002 | User portal — subscription, usage, settings                      |
| **tracker-dashboard-web** | 3003 | Public roadmap, issue tracker, community voting                  |

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

> **Status as of 2026-03-01:** 23 of 25 gap items are now **✅ BUILT**. 2 remain **❌ Not Started** (P3 only).
> The detailed designs below are preserved as reference for the implementations.

### P0 — Foundational ✅ ALL BUILT (6/6)

These are blocking features that nearly every production app needs. All P0 items have been implemented.

---

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

**Current state:** Zero. All logic is request-driven (HTTP request → response).

**Proposed design:**

```
platform-service/src/modules/jobs/
├── types.ts         — JobDefinition, JobRun, JobSchedule schemas
├── registry.ts      — Job registry (register named jobs with cron expressions)
├── runner.ts        — Tick loop: evaluate cron, run due jobs, record outcomes
├── repository.ts    — Cosmos: job_definitions, job_runs containers
└── routes.ts        — Admin: list jobs, trigger manually, view run history, pause/resume
```

**Built-in jobs to ship on day 1:**

| Job                      | Schedule              | Description                                                                                            |
| ------------------------ | --------------------- | ------------------------------------------------------------------------------------------------------ |
| `trial-expiration-check` | Every hour            | Find subscriptions with `status=trialing` past `currentPeriodEnd`, transition to `expired` or `active` |
| `usage-quota-reset`      | Daily at midnight UTC | Reset daily/monthly counters in `usage_daily` container                                                |
| `stale-session-cleanup`  | Every 6 hours         | Remove expired refresh tokens and inactive sessions                                                    |
| `telemetry-ttl-sweep`    | Daily at 3am UTC      | Delete telemetry events past retention TTL (Cosmos TTL is best-effort)                                 |
| `waitlist-reminder`      | Weekly                | Identify stale waitlist entries, mark for follow-up                                                    |
| `license-expiry-check`   | Daily                 | Warn users whose licenses expire within 7 days                                                         |

**Options for the runner:**

- **In-process tick loop** (simplest): `setInterval` in platform-service, with leader election via Cosmos lease
- **Azure Functions timer triggers** (serverless): Lower cost, built-in cron, but adds deployment complexity
- **BullMQ + Redis** (heavy): Best for high-throughput, but adds a Redis dependency

**Recommendation:** Start with in-process tick loop + Cosmos lease for leader election (avoids Redis). Migrate to Azure Functions if job volume grows.

**Admin UI:**

- `/ops/jobs` page: list all registered jobs, last run status, next scheduled run
- Manual trigger button per job
- Run history table with duration, outcome, error details
- Pause/resume toggle per job

**Cosmos containers:**

- `job_definitions` (pk: `/productId`) — name, cron, enabled, lastRunAt, nextRunAt
- `job_runs` (pk: `/productId:jobName`) — runId, startedAt, completedAt, status, error, metrics

---

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

**Current state:** Device registration + preference management only. No email, no push, no SMS.

**Proposed design:**

```
platform-service/src/modules/delivery/
├── types.ts         — DeliveryRequest, DeliveryLog, ChannelConfig schemas
├── channels/
│   ├── email.ts     — SendGrid/Postmark adapter
│   ├── push-apns.ts — Apple Push Notification Service
│   ├── push-fcm.ts  — Firebase Cloud Messaging
│   └── sms.ts       — Twilio/Azure Communication Services (future)
├── renderer.ts      — Template rendering (Handlebars for email bodies)
├── repository.ts    — delivery_log + email_templates containers
├── dispatcher.ts    — Route delivery request to correct channel(s) based on prefs
└── routes.ts        — Admin: send test, view delivery log, manage templates
```

**Email templates to ship on day 1:**

| Template            | Trigger                                    | Description                                  |
| ------------------- | ------------------------------------------ | -------------------------------------------- |
| `welcome`           | `auth.register`                            | Welcome email with getting-started guide     |
| `trial-expiring`    | `jobs.trial-expiration-check` (7d warning) | "Your trial ends in 7 days"                  |
| `trial-expired`     | `jobs.trial-expiration-check`              | "Your trial has ended — upgrade to continue" |
| `password-reset`    | Future: `/auth/forgot-password`            | One-time reset link                          |
| `invitation`        | `invitations.create`                       | "You've been invited to join"                |
| `waitlist-accepted` | `waitlist.invite`                          | "You're in! Here's your access"              |
| `payment-failed`    | `stripe.invoice.payment_failed`            | "We couldn't charge your card"               |
| `license-expiring`  | `jobs.license-expiry-check`                | "Your license expires in 7 days"             |

**Push notification types:**

| Type                   | Channel    | Description                                  |
| ---------------------- | ---------- | -------------------------------------------- |
| `dictation_reminder`   | APNs + FCM | "Haven't dictated today — keep your streak!" |
| `feature_announcement` | APNs + FCM | Admin-triggered announcement                 |
| `subscription_change`  | APNs + FCM | Plan upgraded/downgraded/expired             |

**Cosmos container:**

- `delivery_log` (pk: `/productId:channel:yyyyMM`) — id, userId, channel, template, status (sent/failed/bounced), sentAt, error

**Admin UI:**

- `/ops/delivery` page: delivery log with filters (channel, status, template, date range)
- Template management: list, preview, edit (future: visual editor)
- "Send test" button for each template
- Delivery stats: sent/failed/bounced/opened (with SendGrid webhook integration)

---

#### 2.3 Outbound Webhook Subscriptions ✅ BUILT

> **Implementation:** `modules/webhooks/` (4 source files) — subscription CRUD, HMAC-SHA256 signing, exponential backoff retry (3 attempts), auto-disable after 10 failures, secret rotation, delivery log. Registered in `cosmos-init.ts` (`webhook_subscriptions`, `webhook_deliveries`). Legacy `lib/webhooks.ts` still exists for backward compat.

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

**Current state:** 3 hardcoded webhook dispatchers (invitation redeemed, referral status changed, waitlist joined). No retry. No HMAC signing. No subscription management.

**Proposed design:**

```
platform-service/src/modules/webhooks/
├── types.ts         — WebhookSubscription, WebhookDelivery, WebhookEvent schemas
├── repository.ts    — Cosmos: webhook_subscriptions, webhook_deliveries containers
├── dispatcher.ts    — Match event → subscriptions, queue delivery, HMAC-SHA256 sign
├── delivery.ts      — HTTP POST with exponential backoff retry (3 attempts)
└── routes.ts        — Admin CRUD for subscriptions + delivery log
```

**Event catalog (subscribe to any combination):**

| Event                   | Payload                                        | Source                          |
| ----------------------- | ---------------------------------------------- | ------------------------------- |
| `user.created`          | `{ userId, email, plan }`                      | `auth.register`, `auth.sso`     |
| `user.deleted`          | `{ userId }`                                   | Admin: `DELETE /auth/users/:id` |
| `subscription.created`  | `{ subscriptionId, userId, plan, status }`     | Registration hook               |
| `subscription.changed`  | `{ subscriptionId, oldPlan, newPlan, status }` | Stripe webhook                  |
| `subscription.canceled` | `{ subscriptionId, userId, reason }`           | User action / Stripe            |
| `payment.succeeded`     | `{ invoiceId, amount, userId }`                | Stripe webhook                  |
| `payment.failed`        | `{ invoiceId, amount, userId, retryCount }`    | Stripe webhook                  |
| `invitation.redeemed`   | `{ invitationId, userId }`                     | Invitation module               |
| `referral.completed`    | `{ referralId, referrerId, referredId }`       | Referral module                 |
| `waitlist.joined`       | `{ email, position }`                          | Waitlist module                 |
| `flag.toggled`          | `{ flagId, enabled, percentage }`              | Flags module                    |
| `license.activated`     | `{ licenseId, userId, deviceId }`              | License module                  |
| `license.expired`       | `{ licenseId, userId }`                        | Jobs: license-expiry-check      |

**Security:**

- Every delivery signed with `X-Webhook-Signature: sha256=<HMAC>` using per-subscription secret
- Subscription secret generated at creation time, displayed once, rotatable
- Replay protection: `X-Webhook-Timestamp` header, reject if > 5 min old

**Retry policy:**

- 3 attempts with exponential backoff: 10s → 60s → 300s
- After 3 failures: mark subscription as `failing`, admin notification
- After 10 consecutive failures: auto-disable subscription

**Admin UI:**

- `/ops/webhooks` page: list subscriptions, create/edit/delete, test delivery
- Delivery log: status (success/failed/retrying), response code, duration, payload preview
- Per-subscription health indicator (green/yellow/red based on recent success rate)

**Cosmos containers:**

- `webhook_subscriptions` (pk: `/productId`) — id, url, secret, events[], enabled, failureCount, lastDeliveryAt
- `webhook_deliveries` (pk: `/subscriptionId:yyyyMM`) — id, event, status, attempts[], responseCode, duration

---

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

**Current state:** Some fire-and-forget with unhandled promise rejections (e.g., telemetry cluster updates). No formal event bus.

**Proposed design:**

```
packages/events/
├── src/
│   ├── index.ts     — EventBus class, typed event definitions
│   ├── types.ts     — PlatformEvent union type, EventHandler interface
│   └── memory.ts    — In-memory implementation (default)
```

**Event flow:**

```
API route handler
  → bus.emit('user.created', { userId, email, plan })
    → [handler] audit.record()
    → [handler] webhook.dispatch()
    → [handler] email.sendWelcome()
    → [handler] analytics.track()
```

**Implementation options:**

- **Phase 1:** In-memory `EventEmitter` wrapper with typed events (zero dependencies)
- **Phase 2:** Azure Service Bus adapter for cross-service events
- **Phase 3:** Azure Event Grid for external consumer webhooks

**Typed event definitions (Zod):**

```typescript
const PlatformEvents = {
  'user.created': z.object({ userId: z.string(), email: z.string(), plan: z.string() }),
  'user.deleted': z.object({ userId: z.string() }),
  'subscription.changed': z.object({
    subscriptionId: z.string(),
    oldPlan: z.string(),
    newPlan: z.string(),
  }),
  'payment.failed': z.object({ invoiceId: z.string(), userId: z.string() }),
  // ... all events from webhook catalog
} as const;
```

**Migration from existing `lib/webhooks.ts`:**

- Existing `dispatchInvitationRedeemed()`, `dispatchReferralStatusChanged()`, `dispatchWaitlistJoined()` become event bus subscribers
- Phase 1: Register existing webhooks.ts functions as handlers on the bus
- Phase 2: Replace inline dispatch calls in routes with `bus.emit()`
- Phase 3: Remove `lib/webhooks.ts` once all callers migrated

**Benefits:**

- Audit logging becomes a subscriber, not inline code
- Webhook delivery becomes a subscriber, not inline code
- Email sending becomes a subscriber, not inline code
- New features can subscribe to events without modifying existing modules

---

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

**Current state:** If a user forgets their password, there is no recovery path. Registration accepts any email without verification.

**Proposed additions to `auth` module:**

**Password reset flow:**

1. `POST /auth/forgot-password` — accepts `{ email, productId }`, generates a time-limited reset token (UUID), stores hash in `password_reset_tokens` container, sends email with reset link (via delivery module §2.2)
2. `POST /auth/reset-password` — accepts `{ token, newPassword }`, validates token, updates `passwordHash`, invalidates token, optionally revokes all sessions (§2.7)

**Email verification flow:**

1. On register: generate verification token, store in `email_verifications` container, send email
2. `POST /auth/verify-email` — accepts `{ token }`, marks user email as verified
3. `POST /auth/resend-verification` — rate-limited, re-sends verification email
4. Add `emailVerified: boolean` field to `UserDoc`

**Reset token document:**

```typescript
interface PasswordResetToken {
  id: string; // UUID
  productId: string;
  userId: string;
  tokenHash: string; // SHA-256 hash of the token (raw token sent via email)
  expiresAt: string; // 1 hour from creation
  usedAt?: string;
  createdAt: string;
}
```

**Security considerations:**

- Store hash of token, not raw token (same pattern as API tokens)
- Tokens expire in 1 hour
- Rate limit: 3 reset requests per email per hour
- After successful reset, invalidate all existing sessions
- Log all reset attempts to audit

**Cosmos container:**

- `password_reset_tokens` (pk: `/productId`) — short-lived, TTL 24h auto-expiry

**Dependency:** Requires email delivery (§2.2) for sending reset links and verification emails. Can ship the endpoints first with `req.log.info`-logged URLs for dev/testing (never `console.log`).

---

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

**Current state:** `monitoring/health-check.ts` polls services and prints to stdout. No persistent status, no incident history, no public URL.

**Proposed design:**

**Option A — Self-hosted (minimal):**

```
platform-service/src/modules/status/
├── types.ts         — ServiceStatus, Incident, MaintenanceWindow schemas
├── repository.ts    — Cosmos: service_status, incidents containers
├── poller.ts        — Periodic health poll (reuses @bytelyst/monitoring)
└── routes.ts        — Public: GET /public/status, GET /public/status/history
```

**Option B — External (Instatus, Statuspage, or Upptime):**

- Upptime (GitHub-based, free, open-source) — runs as a GitHub Action, publishes to GitHub Pages
- Better for public credibility (hosted on a separate domain)

**Recommendation:** Option A for internal/admin use, Option B for public-facing.

**Status page data model:**

| Field                | Type       | Description                                            |
| -------------------- | ---------- | ------------------------------------------------------ |
| `services`           | array      | Current status per service (operational/degraded/down) |
| `incidents`          | array      | Active and past incidents with timeline                |
| `maintenanceWindows` | array      | Scheduled maintenance with start/end times             |
| `overallStatus`      | enum       | `operational` / `degraded` / `major_outage`            |
| `lastCheckedAt`      | ISO string | When the poller last ran                               |

**Admin UI:**

- `/ops/status` page (or extend existing Mission Control `/ops`): service health cards with history sparklines
- Incident management: create/update/resolve incidents with public-facing messages
- Maintenance scheduling: create windows with auto-banners

---

### P1 — Operational Maturity ✅ ALL BUILT (5/5)

These components improve reliability, debuggability, and operational efficiency. All P1 items have been implemented.

---

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

**Current state:** JWT tokens with expiry. No session tracking. No revocation list. Refresh tokens are stateless.

**Proposed design:**

```
platform-service/src/modules/sessions/
├── types.ts         — SessionDoc, CreateSessionInput schemas
├── repository.ts    — Cosmos: sessions container (pk: /userId)
├── middleware.ts    — Session validation (check revocation on each request)
└── routes.ts        — User: list my sessions, revoke one, revoke all
                     — Admin: list user sessions, force-revoke
```

**Session document:**

```typescript
interface SessionDoc {
  id: string; // session ID (embedded in JWT)
  productId: string;
  userId: string;
  deviceId?: string; // linked to license device
  platform: string; // ios, android, desktop, web
  ipAddress: string;
  userAgent: string;
  lastActiveAt: string;
  createdAt: string;
  revokedAt?: string;
  expiresAt: string;
}
```

**Endpoints:**

- `GET /sessions` — list my active sessions
- `DELETE /sessions/:id` — revoke specific session
- `DELETE /sessions` — revoke all sessions (sign out everywhere)
- `GET /sessions/user/:userId` — admin: list user's sessions
- `DELETE /sessions/user/:userId` — admin: force-revoke all

**Integration:** Refresh token endpoint creates a session. Auth middleware checks session isn't revoked (Cosmos point-read by session ID, cached in-memory with short TTL).

---

#### 2.8 Database Migration & Schema Evolution Tracker ✅ BUILT

> **Implementation:** `src/migrations/` (3 source files: types.ts, registry.ts, runner.ts) — idempotent migration runner on startup, Cosmos `migrations` container for tracking, best-effort (failures don’t block startup). Admin can query via `listMigrations()`.

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

**Current state:** No migration tracking. Schema changes are applied ad-hoc.

**Proposed design:**

```
platform-service/src/migrations/
├── runner.ts        — Run pending migrations on startup (idempotent)
├── registry.ts      — List of migration files, ordered by version
└── migrations/
    ├── 001_add_productId_to_legacy_users.ts
    ├── 002_create_telemetry_containers.ts
    └── ...
```

**Migration document (in `migrations` container):**

```typescript
interface MigrationDoc {
  id: string; // "001_add_productId_to_legacy_users"
  productId: string; // "platform"
  version: number;
  description: string;
  appliedAt: string;
  durationMs: number;
  status: 'applied' | 'failed' | 'rolled_back';
  error?: string;
}
```

**Behavior:**

- On service startup, runner checks `migrations` container for applied versions
- Runs any unapplied migrations in order
- Each migration is idempotent (safe to re-run)
- Failed migrations are recorded but don't block startup (logged as warnings)
- Admin UI: `/ops/migrations` page showing applied/pending/failed

---

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

**Current state:** Waitlist has a CSV export endpoint. Nothing else supports bulk operations.

**Proposed design:**

```
platform-service/src/modules/exports/
├── types.ts         — ExportJob, ExportFormat schemas
├── repository.ts    — Cosmos: export_jobs container
├── workers/
│   ├── users.ts     — Export users as CSV/JSON
│   ├── audit.ts     — Export audit log
│   ├── telemetry.ts — Export telemetry events
│   ├── usage.ts     — Export usage data
│   └── subscriptions.ts — Export subscriptions
└── routes.ts        — POST /exports (start), GET /exports (list), GET /exports/:id/download
```

**Flow:**

1. Admin POST `/api/exports` → `{ type: 'users', format: 'csv', filters: { plan: 'free' } }`
2. Background job runs query, writes result to blob storage (via existing `blob` module)
3. Job status updates: `pending` → `processing` → `ready` / `failed`
4. Admin downloads from signed blob URL (SAS token via `@bytelyst/blob`)

**Dependencies:** `blob` module (existing) for storage, `jobs` module (§2.1) for auto-cleanup of expired exports.

**Supported exports:**

- Users (with filters: plan, status, date range)
- Audit log (with filters: action, userId, date range)
- Telemetry events (with filters: platform, eventType, date range)
- Usage records (with filters: userId, date range)
- Subscriptions (with filters: plan, status)
- Licenses (with filters: status, plan)

**Admin UI:**

- `/ops/exports` page: create new export, list past exports, download links
- Progress indicator for running exports
- Auto-cleanup: delete export blobs after 7 days

---

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

**Current state:** `settings/kill-switch` endpoint returns boolean per product. Clients check and fully disable themselves.

**Proposed design:**

Extend the existing `settings` module:

```typescript
interface MaintenanceConfig {
  mode: 'off' | 'read_only' | 'maintenance' | 'emergency';
  message: string; // Shown to users
  adminMessage?: string; // Shown to admins
  bypassRoles: string[]; // Roles that can bypass (e.g., ['admin', 'super_admin'])
  bypassIPs: string[]; // IP addresses that bypass
  scheduledStart?: string; // ISO — for planned maintenance
  scheduledEnd?: string;
  affectedServices: string[]; // ['api', 'dictation', 'extraction'] or ['*']
  updatedAt: string;
  updatedBy: string;
}
```

**Modes:**

- `off` — Normal operation
- `read_only` — GET requests allowed, writes blocked (for database maintenance)
- `maintenance` — All requests return 503 with message (except admin bypass)
- `emergency` — Kill switch + maintenance message + all clients show error

**Endpoints:**

- `GET /settings/maintenance` — Public: check current mode + message
- `PUT /settings/maintenance` — Admin: update mode, message, bypass rules
- `GET /settings/maintenance/schedule` — Upcoming maintenance windows

**Client integration:**

- Clients poll `/settings/maintenance` alongside kill-switch check
- If `mode !== 'off'`, show banner with `message`
- If `mode === 'maintenance'`, disable write operations with user-facing explanation

**Admin UI:**

- Extend existing Settings page or add `/ops/maintenance`
- Mode toggle (off/read-only/maintenance/emergency)
- Message editor with preview
- Schedule builder with start/end date pickers
- Bypass IP whitelist management

**Storage:** Maintenance config is a single document per product in the existing `settings` container (field: `maintenanceConfig`). No new Cosmos container needed.

---

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

**Current state:** In-memory sliding window rate limiter with configurable rules. No persistence, no admin visibility.

**Proposed design:**

Extend `ratelimit` module:

```typescript
interface RateLimitEntry {
  key: string; // userId or IP
  productId: string;
  currentCount: number;
  windowStart: string;
  wasLimited: boolean;
  lastLimitedAt?: string;
}

interface IPRule {
  id: string;
  productId: string;
  ip: string; // CIDR notation supported
  action: 'allow' | 'deny';
  reason: string;
  createdBy: string;
  createdAt: string;
  expiresAt?: string; // Temporary blocks
}
```

**Additional endpoints:**

- `GET /ratelimit/stats` — Admin: top rate-limited keys, total 429s in last hour/day
- `GET /ratelimit/blocked` — Admin: currently blocked keys
- `POST /ratelimit/ip-rules` — Admin: add IP allow/deny rule
- `GET /ratelimit/ip-rules` — Admin: list rules
- `DELETE /ratelimit/ip-rules/:id` — Admin: remove rule

**Admin UI:**

- `/ops/rate-limits` page: real-time rate limit stats
- Top offenders table (most 429 responses)
- IP rules management (allow/deny with expiry)
- Per-user rate limit override

**Cosmos container:**

- `ip_rules` (pk: `/productId`) — persistent IP allow/deny rules
- Rate limit stats remain in-memory (ephemeral); no persistence needed for counters

---

### P2 — Product Intelligence ✅ ALL BUILT

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 ✅ 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.

**Current state:** `flags` module with boolean flags and FNV-1a deterministic rollout.

**Proposed design:**

Extend `flags` module or create sibling `experiments` module:

```
platform-service/src/modules/experiments/
├── types.ts         — Experiment, Variant, ExperimentMetric schemas
├── repository.ts    — Cosmos: experiments container
├── assignment.ts    — Deterministic variant assignment (extend FNV-1a)
├── analysis.ts      — Statistical significance calculation
└── routes.ts        — Admin CRUD + results endpoint
```

**Experiment document:**

```typescript
interface ExperimentDoc {
  id: string;
  productId: string;
  name: string;
  hypothesis: string;
  status: 'draft' | 'running' | 'paused' | 'concluded';
  variants: Variant[]; // [{id: 'control', weight: 50}, {id: 'treatment', weight: 50}]
  targetingRules: FlagTargetingRules; // Reuse from flags module (platforms, versions, percentage)
  primaryMetric: string; // e.g., 'dictation_completed_rate'
  secondaryMetrics: string[];
  startedAt?: string;
  concludedAt?: string;
  winningVariant?: string;
  sampleSize: number;
  results?: ExperimentResults;
}
```

**Admin UI:**

- `/experiments` page: list experiments, create new, view results
- Results view: conversion rates per variant, confidence interval, statistical significance indicator
- "Conclude" action: pick winner, auto-convert to feature flag

---

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

**Current state:** Raw `usage_daily` records. No aggregation.

**Proposed design:**

```
platform-service/src/modules/analytics/
├── types.ts         — MetricRollup, CohortEntry, FunnelStep schemas
├── repository.ts    — Cosmos: analytics_rollups container
├── rollup-jobs/
│   ├── dau-wau-mau.ts    — Daily/weekly/monthly active users
│   ├── retention.ts      — Cohort retention (D1, D7, D14, D30)
│   ├── funnel.ts         — Conversion funnels (signup → activate → dictate → subscribe)
│   └── feature-adoption.ts — Per-feature usage rates
└── routes.ts        — Admin: GET /analytics/dau, /retention, /funnel, /adoption
```

**Rollup schedule (via jobs module):**

- DAU: every hour (incremental)
- WAU/MAU: daily at 1am UTC
- Retention cohorts: daily at 2am UTC
- Funnels: daily at 2:30am UTC

**Key metrics:**

- **DAU/WAU/MAU** — with breakdown by platform, plan
- **Retention cohorts** — "Of users who signed up in week X, what % are active in week X+1, X+4?"
- **Conversion funnel** — signup → first dictation → 5th dictation → subscription
- **Feature adoption** — % of active users using each major feature
- **Revenue metrics** — MRR, churn rate, ARPU, LTV (from subscriptions + Stripe data)

**Admin UI:**

- Extend dashboard home or create `/analytics` page
- Charts: DAU/WAU/MAU line chart, retention heatmap, funnel bar chart, MRR trend

---

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

**Current state:** Public roadmap allows feature submissions and voting. No in-app feedback widget.

**Proposed design:**

```
platform-service/src/modules/feedback/
├── types.ts         — FeedbackEntry, FeedbackType, DeviceContext schemas
├── repository.ts    — Cosmos: feedback container (pk: /productId)
└── routes.ts        — POST /feedback (authenticated), GET /feedback (admin query)
```

**Feedback types:**

- `bug_report` — with device context, screenshot URL (blob), reproduction steps
- `feature_request` — auto-creates tracker item in `items` module
- `nps_survey` — score (0-10), comment, context
- `general` — free-form text

**Client integration:**

- Shake-to-report (iOS/Android) or keyboard shortcut (Desktop)
- Auto-attach: device model, OS version, app version, current screen, last 10 telemetry events
- Screenshot capture (optional, privacy-respecting)

**Admin UI:**

- `/feedback` page: list feedback with filters (type, platform, date range, NPS score range)
- Quick actions: convert to tracker item, reply, dismiss
- NPS dashboard: score distribution over time, detractor/promoter breakdown

---

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

**Current state:** No impersonation capability.

**Proposed design:**

**Endpoint:**

- `POST /auth/impersonate` — Admin only. Accepts `{ targetUserId }`. Returns a scoped shadow token.

**Shadow token properties:**

- Contains `impersonatedBy: adminUserId` claim
- Read-only by default (no writes unless explicitly allowed)
- Expires in 15 minutes (non-renewable)
- All actions logged to audit with `impersonatedBy` field
- Visible banner in dashboard: "You are viewing as [user name] — all actions are audited"

**Admin UI:**

- On the user detail page (`/users/:id`), add "View as User" button
- Opens user dashboard in new tab with shadow token
- Impersonation sessions listed on `/ops/audit` with filter

---

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

**Current state:** `CHANGELOG.md` exists in the repo but nothing in-app.

**Proposed design:**

```
platform-service/src/modules/changelog/
├── types.ts         — ChangelogEntry, ReleaseNote schemas
├── repository.ts    — Cosmos: changelog container (pk: /productId)
└── routes.ts        — Public: GET /changelog (paginated)
                     — Admin: CRUD changelog entries
```

**Entry document:**

```typescript
interface ChangelogEntry {
  id: string;
  productId: string;
  version: string; // "1.2.0"
  title: string;
  body: string; // Markdown
  category: 'feature' | 'improvement' | 'bugfix' | 'security';
  platforms: string[]; // ['ios', 'android', 'desktop', 'web']
  publishedAt?: string;
  isDraft: boolean;
  createdBy: string;
}
```

**Client integration:**

- App checks `GET /api/changelog?since=<lastSeenVersion>` on launch
- If new entries exist, show "What's New" modal
- User can dismiss; `lastSeenVersion` stored in settings

**Admin UI:**

- `/changelog` page: create/edit/publish entries with Markdown editor
- Preview mode before publishing
- Schedule publishing for future date

---

### P3 — Scale & Polish (1 of 9 BUILT, 8 deferred)

These components are important for scale, security, and developer experience, but are lower urgency.

---

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

**Proposed approach:**

- Azure CDN or Cloudflare in front of blob storage
- Image resize on upload (Sharp) for avatars: 64px, 128px, 256px variants
- Cache headers: `Cache-Control: public, max-age=31536000, immutable` for content-addressed assets
- Release binaries served via CDN for faster desktop app updates

---

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

**Proposed approach:**

- URL prefix: `/v1/api/...`
- Deprecation header: `Sunset: <date>` + `Deprecation: true`
- Version lifecycle: `current` → `deprecated` (6 months notice) → `retired`
- OpenAPI spec generated per version
- Fastify plugin that routes to versioned handlers

---

#### 2.19 OpenAPI / Auto-Generated API Docs ✅ BUILT

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

**Current state:** `@fastify/swagger` is configured with title/description but route schemas aren't connected via `@fastify/type-provider-zod`. Swagger UI may already be partially served but without route-level detail.

**Proposed approach:**

- Wire `@fastify/type-provider-zod` to connect existing Zod schemas to Fastify route definitions
- Verify `@fastify/swagger-ui` is serving at `/documentation` on platform-service
- Add route-level `schema: { body, querystring, params, response }` using existing Zod schemas
- Export OpenAPI JSON at `/documentation/json`
- Admin dashboard links to platform-service Swagger UI

---

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

**Proposed approach:**

- `translations` Cosmos container (pk: `/productId:locale`)
- Admin UI: string management with translation status per locale
- Client SDK: fetch translations on launch, cache locally
- Fallback chain: requested locale → base locale → English

---

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

**Proposed approach:**

- **Phase 1:** Cosmos DB full-text search (preview feature, no extra cost)
- **Phase 2:** Azure AI Search for richer capabilities (fuzzy matching, facets, suggestions)
- Admin UI: unified search bar across entities (users, items, audit logs)

---

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

**Proposed design (future):**

```
users → belong to → organizations → have → teams → own → resources
```

This is a major architectural expansion. Defer until enterprise tier is validated.

---

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

**Proposed approach:**

- Admin-configurable retention policies per container
- Scheduled job (from §2.1) runs cleanup
- Default policies: audit (365 days), telemetry (30 days), sessions (90 days), export files (7 days)
- Admin UI: `/ops/retention` page showing policies and next cleanup run

---

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

**Proposed approach:**

- Admin UI: `/ops/backups` page showing Azure backup status
- Manual export to blob (scheduled job from §2.1)
- Restore button: triggers Azure Cosmos point-in-time restore API
- Cross-region replication status indicator

---

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

**Proposed flow:**

1. `invoice.payment_failed` → send "payment failed" email (§2.2) + in-app banner
2. After 3 failures (Stripe Smart Retries) → send "final warning" email
3. After grace period (7 days) → downgrade to free plan + email notification
4. All transitions logged to audit

**Integration:** Stripe webhook handler (existing) + email delivery (§2.2) + scheduled job (§2.1) for grace period enforcement.

---

## 3. Implementation Priority Matrix

| 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            | ✅ Complete    | `modules/webhooks/` — 4 files, HMAC signing, retry, auto-disable        |
| **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                    | ✅ Complete    | `@fastify/swagger-ui` at `/documentation`, auto-generated spec          |
| **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                    | ✅ Complete    | `src/migrations/` — runner on startup, Cosmos tracking                  |
| **Later**    | 2.17–2.18, 2.20–2.25                 | ❌ Not Started | CDN, versioning, i18n, search, multi-tenant, retention, backup, dunning |

**Summary:** 23 of 25 gap items ✅ complete. 2 ❌ not started (P3 scale items only: CDN, versioning, i18n, search, multi-tenant, retention, backup, dunning).

**All P0, P1, and P2 items are complete.** Only lower-priority P3 scale/polish items remain.

---

## 4. New Cosmos Containers & Cost Impact

Each new component introduces Cosmos containers. Cosmos DB Serverless charges per RU consumed + storage, so idle containers cost only storage (~$0.25/GB/month).

| Component              | New Containers                                 | Partition Key                             | Est. TTL        | Est. Daily RU                       |
| ---------------------- | ---------------------------------------------- | ----------------------------------------- | --------------- | ----------------------------------- |
| **2.1 Jobs**           | `job_definitions`, `job_runs`                  | `/productId`, `/productId:jobName`        | runs: 90d       | ~50 RU (low volume)                 |
| **2.2 Email/Push**     | `delivery_log`, `email_templates`              | `/productId:channel:yyyyMM`, `/productId` | log: 90d        | ~200 RU                             |
| **2.3 Webhooks**       | `webhook_subscriptions`, `webhook_deliveries`  | `/productId`, `/subscriptionId:yyyyMM`    | deliveries: 30d | ~100 RU                             |
| **2.5 Password Reset** | `password_reset_tokens`, `email_verifications` | `/productId`, `/productId`                | 24h auto        | ~10 RU                              |
| **2.6 Status**         | `service_status`, `incidents`                  | `/productId`, `/productId`                | None            | ~20 RU                              |
| **2.7 Sessions**       | `sessions`                                     | `/userId`                                 | 90d             | ~500 RU (read-heavy)                |
| **2.8 Migrations**     | `migrations`                                   | `/productId`                              | None            | ~5 RU (startup only)                |
| **2.9 Exports**        | `export_jobs`                                  | `/productId`                              | 30d             | ~20 RU                              |
| **2.12 Experiments**   | `experiments`                                  | `/productId`                              | None            | ~50 RU                              |
| **2.13 Analytics**     | `analytics_rollups`                            | `/productId:metric:period`                | None            | ~300 RU (write-heavy during rollup) |
| **2.11 IP Rules**      | `ip_rules`                                     | `/productId`                              | None (manual)   | ~10 RU                              |
| **2.14 Feedback**      | `feedback`                                     | `/productId`                              | None            | ~50 RU                              |
| **2.16 Changelog**     | `changelog`                                    | `/productId`                              | None            | ~10 RU                              |
| **2.20 i18n**          | `translations`                                 | `/productId:locale`                       | None            | ~100 RU (read-heavy, cacheable)     |
| **2.23 Retention**     | `retention_policies`                           | `/productId`                              | None            | ~5 RU                               |

**Total new containers:** ~19 (across all phases)
**Existing containers:** 27 (defined in `cosmos-init.ts`: products, users, settings, devices, notification_prefs, audit_log, feature_flags, invitation_codes, referrals, subscriptions, payments, licenses, plans, usage_daily, api_tokens, tracker_items, comments, votes, themes, waitlist, memory_items, daily_briefs, reflections, brain_insights, telemetry_events, telemetry_error_clusters, telemetry_collection_policies). Note: `promos` module uses Stripe API directly — no Cosmos container.
**Cost impact:** Minimal for Serverless tier — idle containers only consume storage. Active containers during job runs add burst RU.

**Recommendation:** Register all new containers in `cosmos-init.ts` alongside existing ones. Use TTL liberally for transient data (tokens, deliveries, job runs) to keep storage bounded.

---

## 5. New Environment Variables

New components will require additional env vars. All should be added to `.env.example` files in both repos and documented.

| Component            | Variable                      | Example                          | Required                  |
| -------------------- | ----------------------------- | -------------------------------- | ------------------------- |
| **2.1 Jobs**         | `JOB_RUNNER_ENABLED`          | `true`                           | No (default: true)        |
| **2.1 Jobs**         | `JOB_TICK_INTERVAL_MS`        | `60000`                          | No (default: 60s)         |
| **2.2 Email**        | `SENDGRID_API_KEY`            | `SG.xxx`                         | Yes (for email delivery)  |
| **2.2 Email**        | `EMAIL_FROM_ADDRESS`          | `noreply@lysnrai.com`            | Yes                       |
| **2.2 Email**        | `EMAIL_FROM_NAME`             | `LysnrAI`                        | No                        |
| **2.2 Push**         | `APNS_KEY_ID`                 | `ABC123`                         | Yes (for iOS push)        |
| **2.2 Push**         | `APNS_TEAM_ID`                | `748N7QPX7J`                     | Yes                       |
| **2.2 Push**         | `APNS_KEY_PATH`               | `./certs/AuthKey.p8`             | Yes                       |
| **2.2 Push**         | `FCM_SERVICE_ACCOUNT_JSON`    | `{...}`                          | Yes (for Android push)    |
| **2.5 Auth**         | `PASSWORD_RESET_URL_BASE`     | `https://app.lysnrai.com/reset`  | Yes                       |
| **2.5 Auth**         | `EMAIL_VERIFY_URL_BASE`       | `https://app.lysnrai.com/verify` | Yes                       |
| **2.10 Maintenance** | `MAINTENANCE_MODE`            | `off`                            | No (default: off)         |
| **2.10 Maintenance** | `MAINTENANCE_BYPASS_IPS`      | `10.0.0.1,10.0.0.2`              | No                        |
| **2.3 Webhooks**     | `WEBHOOK_DELIVERY_TIMEOUT_MS` | `5000`                           | No (default: 5s)          |
| **2.3 Webhooks**     | `WEBHOOK_MAX_RETRIES`         | `3`                              | No (default: 3)           |
| **2.7 Sessions**     | `SESSION_TTL_DAYS`            | `90`                             | No (default: 90)          |
| **2.7 Sessions**     | `SESSION_CACHE_TTL_MS`        | `30000`                          | No (default: 30s)         |
| **2.19 OpenAPI**     | `SWAGGER_UI_ENABLED`          | `true`                           | No (default: true in dev) |

**Secret management:** `SENDGRID_API_KEY`, `APNS_*`, and `FCM_*` should be added to Azure Key Vault as `lysnr-sendgrid-api-key`, `lysnr-apns-key-id`, etc. Update `LYSNR_SECRETS` in `@bytelyst/config` to include them.

---

## 6. Quick Reference — Where Things Live

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

---

## Appendix A: Risks & Open Questions

| #   | Topic                              | Risk / Question                                                                                                                                     | Mitigation                                                                                                                                                                     |
| --- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1   | **Leader election for jobs**       | In-process tick loop with Cosmos lease — what happens during deploys? Two instances may briefly both hold leases.                                   | Cosmos lease has a built-in TTL. Use 30s lease with 10s renewal. During deploy overlap, the old instance's lease expires before the new one acquires. Jobs must be idempotent. |
| 2   | **Email deliverability**           | SendGrid requires domain verification (SPF/DKIM/DMARC). Without it, emails land in spam.                                                            | Set up `lysnrai.com` domain authentication in SendGrid before shipping §2.2. Budget 1–2 days for DNS propagation.                                                              |
| 3   | **Session validation latency**     | Checking Cosmos on every request for session revocation adds ~5–10ms per request.                                                                   | In-memory cache with 30s TTL (§2.7). Revocation is eventually consistent — acceptable trade-off for most apps. Document the 30s window.                                        |
| 4   | **Cosmos container proliferation** | 28 existing + 19 new = 47 containers. Serverless tier has no per-container cost, but management complexity grows.                                   | Group related containers by module. Document all containers in `cosmos-init.ts`. Consider container-per-module naming convention.                                              |
| 5   | **Event bus ordering guarantees**  | In-memory `EventEmitter` has no ordering guarantees across handlers. If audit must record before webhook fires, ordering matters.                   | Phase 1: Document that handlers run concurrently with no ordering. If ordering is needed, use handler priority weights or sequential mode.                                     |
| 6   | **Push notification certificates** | APNs requires yearly certificate renewal. If it expires, all iOS push silently stops.                                                               | Add `apns-cert-expiry-check` to scheduled jobs (§2.1). Alert admin 30 days before expiry.                                                                                      |
| 7   | **Webhook abuse**                  | External subscribers could register slow endpoints that back up the delivery queue.                                                                 | Per-subscription timeout (5s default), circuit breaker after 10 consecutive failures, auto-disable.                                                                            |
| 8   | **Migration rollback**             | Cosmos is schemaless — some migrations (e.g., partition key changes) are irreversible.                                                              | Mark migrations as `reversible: true/false`. Require manual approval for irreversible migrations. Always back up before running.                                               |
| 9   | **MindLyst parity**                | MindLyst web uses Cosmos directly (in-memory fallback). Shared components (email, sessions, webhooks) must work for MindLyst too, not just LysnrAI. | All new modules use `productId` for multi-product isolation. MindLyst can consume the same platform-service APIs.                                                              |
| 10  | **Priority conflicts**             | Sprint plan assumes available engineering bandwidth. If telemetry or mobile work takes priority, these sprints slip.                                | Treat sprint assignments as relative ordering, not calendar commitments. Re-evaluate after each sprint.                                                                        |

---

## Appendix B: Component Dependency Graph

```
                    ┌─────────────────────┐
                    │   Event Bus (2.4)    │
                    └─────────┬───────────┘
                              │ emits to subscribers
        ┌───────────┼───────────┼───────────┐
        │           │           │           │
        ▼           ▼           ▼           ▼
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│ Email/Push│ │ Webhook   │ │ Audit Log │ │ Analytics  │
│ (2.2)     │ │ (2.3)     │ │ (existing)│ │ (2.13)    │
└─────┬─────┘ └───────────┘ └───────────┘ └───────────┘
      │
      │ sends
      ▼
┌───────────┐
│ Password  │
│ Reset(2.5)│
└───────────┘

┌───────────────┐──▶┌─────────────────┐   ┌─────────────────┐
│ Scheduled     │   │ Analytics       │   │ Blob Storage    │
│ Jobs (2.1)    │   │ Rollups (2.13)  │   │ (existing)      │
└───────┬───────┘   └─────────────────┘   └────────┬────────┘
        │                                       │
        │ triggers on schedule                   ▲ writes exports
        ▼                                       │
┌───────────────┐   ┌─────────────────┐   ┌─────────────────┐
│ Trial Expiry  │   │ Usage Reset     │   │ Data Export      │
│ (2.1 job)     │   │ (2.1 job)       │   │ (2.9)           │
└───────────────┘   └─────────────────┘   └─────────────────┘

┌───────────────┐   ┌─────────────────┐   ┌─────────────────┐
│ Billing       │──▶│ Email/Push      │   │ Retention        │
│ Dunning(2.25) │   │ Delivery (2.2)  │   │ Cleanup (2.23)   │
└───────────────┘   └─────────────────┘   └─────────────────┘
```

---

## Appendix C: Review Findings

Systematic review performed 2026-02-17. All issues below have been fixed inline.

| #   | Severity | Section  | Finding                                                                                                                                                      | Fix                                                                                                                     |
| --- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| 1   | **Bug**  | §1.3     | Test count stale: said "158+ tests" — actual count is **621** (verified via `grep -c 'it(' *.test.ts`).                                                      | Updated to 621.                                                                                                         |
| 2   | **Bug**  | §1.1     | Endpoint column inconsistent: some modules said "CRUD" (vague, could be 4–8 routes), others had exact counts.                                                | Replaced all "CRUD" with actual route counts.                                                                           |
| 3   | **Bug**  | §2.5     | Said "console-logged URLs for dev/testing" — violates project rule: never `console.log` in production code.                                                  | Changed to `req.log.info`.                                                                                              |
| 4   | **Bug**  | §2.12    | `ExperimentDoc.targetingRules: {}` — meaningless empty object type.                                                                                          | Changed to `FlagTargetingRules` (reuse from flags module).                                                              |
| 5   | **Bug**  | §2.3     | Webhook event `user.deleted` source said `auth.delete` — no such endpoint name. Actual route is `DELETE /auth/users/:id` (admin action).                     | Fixed source column.                                                                                                    |
| 6   | **Bug**  | §4       | `email_verifications` container (from §2.5) missing from Cosmos table. Only `password_reset_tokens` was listed.                                              | Added `email_verifications` to §2.5 row.                                                                                |
| 7   | **Bug**  | §4       | Existing container count said "~25+" — actual is **27** (counted from `cosmos-init.ts`; `promos` uses Stripe API directly, no Cosmos container).             | Updated to 27 with full container list.                                                                                 |
| 8   | **Bug**  | §4       | Total new containers said "~17" — after adding `email_verifications` and `ip_rules`, count is **19**.                                                        | Updated.                                                                                                                |
| 9   | **Gap**  | §2.2     | No clarity on email template storage strategy. `renderer.ts` mentioned but not whether templates are Cosmos-stored or file-based.                            | Clarified: `repository.ts` now references `delivery_log + email_templates` containers.                                  |
| 10  | **Gap**  | §2.4     | No migration strategy from existing `lib/webhooks.ts` to new event bus pattern.                                                                              | Added "Migration from existing `lib/webhooks.ts`" subsection with 3-phase plan.                                         |
| 11  | **Gap**  | §2.10    | Maintenance mode proposed extending `settings` module but didn't clarify storage location. Missing from §4 Cosmos table.                                     | Added: stored as single document per product in existing `settings` container (no new container needed).                |
| 12  | **Gap**  | §2.11    | IP rules need persistence but no container was mentioned. Missing from §4 table.                                                                             | Added `ip_rules` container (pk: `/productId`) to both §2.11 and §4 table.                                               |
| 13  | **Gap**  | §2.9     | Data Export didn't mention blob module dependency (exports written to blob storage).                                                                         | Added explicit dependency note on `blob` module and `jobs` module for cleanup.                                          |
| 14  | **Gap**  | §5       | Missing env vars for webhooks (timeout, retries) and sessions (TTL, cache TTL).                                                                              | Added 4 new env vars: `WEBHOOK_DELIVERY_TIMEOUT_MS`, `WEBHOOK_MAX_RETRIES`, `SESSION_TTL_DAYS`, `SESSION_CACHE_TTL_MS`. |
| 15  | **Gap**  | §6       | Quick Reference missing MindLyst repo (`learning_multimodal_memory_agents`). Doc scope says "ByteLyst platform" which includes MindLyst.                     | Added MindLyst native app and web entries. Also added `cosmos-init.ts` path.                                            |
| 16  | **Gap**  | Appendix | Dependency graph incomplete: missing Jobs → Data Export connection, missing Blob → Data Export dependency, downstream jobs not labeled with section numbers. | Rewrote graph with all connections and section labels.                                                                  |
| 17  | **Gap**  | Overall  | No "Risks & Open Questions" section — design docs should call out unknowns.                                                                                  | Added Appendix A with 10 risk items and mitigations.                                                                    |
| 18  | **Gap**  | TOC      | Table of Contents didn't include Appendix sections.                                                                                                          | Added Appendix A, B, C to TOC.                                                                                          |
| 19  | **Gap**  | §2.5     | Password reset cross-referenced "§2.6" for sessions but sessions was renumbered to §2.7 in previous edit pass.                                               | Fixed to §2.7 (caught in prior pass).                                                                                   |
| 20  | **Gap**  | §1.5     | Infrastructure table was missing Swagger/OpenAPI (partially wired) and Prometheus metrics (partially enabled).                                               | Added in prior pass — verified still present.                                                                           |

---

_This document is a living brainstorm. Items will be promoted to dedicated design docs (like `CLIENT_TELEMETRY_DESIGN.md`) as they move into implementation._
