# ByteLyst Common Platform — Complete Inventory

> **Purpose:** Comprehensive reference for all reusable components, services, SDKs, and tools available to ByteLyst product teams.
> **Repo:** `learning_ai_common_plat`
> **Last Updated:** 2026-03-21

---

## 1. Quick Stats

| Category              | Count   | Notes                                                                |
| --------------------- | ------- | -------------------------------------------------------------------- |
| **Shared Packages**   | 58      | `@bytelyst/*` — consumed via `file:` or `workspace:*`                |
| **Platform Services** | 4       | `platform-service`, `extraction-service`, `mcp-server`, `monitoring` |
| **Dashboards**        | 3       | `admin-web`, `tracker-web`, `ux-lab`                                 |
| **Platform SDKs**     | 3       | Swift, Kotlin, React Native                                          |
| **Platform Modules**  | 63      | platform-service route modules                                       |
| **MCP Namespaces**    | 14      | mcp-server tool namespaces + A2A pipelines                           |
| **Product Configs**   | 7       | `products/` manifests for each product                               |
| **Cosmos Containers** | ~65+    | Shared + product-specific                                            |
| **Total Tests**       | ~2,200+ | Service + package + SDK tests (238 test files in this repo alone)    |

---

## 2. Shared Packages (`@bytelyst/*`)

### 2.1 Core Infrastructure

| Package             | Purpose                     | Exports                                                                                                                            | Consumers                 |
| ------------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `@bytelyst/errors`  | Typed HTTP errors (400-429) | `ServiceError`, `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `TooManyRequestsError` | All services              |
| `@bytelyst/cosmos`  | Azure Cosmos DB client      | `getCosmosClient`, `getDatabase`, `getContainer`, `registerContainers`, `getRegisteredContainer`, `initializeAllContainers`        | All services + dashboards |
| `@bytelyst/config`  | Env loading + Key Vault     | `loadConfig`, `loadProductIdentity`, `resolveKeyVaultSecrets`, `loadProductManifest`, `ProductManifestSchema`                      | All services              |
| `@bytelyst/logger`  | Structured logging          | Pino-based wrapper                                                                                                                 | All services              |
| `@bytelyst/testing` | Shared test utilities       | Fastify inject helpers, mocks                                                                                                      | All test suites           |

### 2.2 Auth & Identity

| Package                 | Purpose                      | Exports                                                                          | Consumers                 |
| ----------------------- | ---------------------------- | -------------------------------------------------------------------------------- | ------------------------- |
| `@bytelyst/auth`        | JWT + password hashing       | `createJwtUtils`, `hashPassword`, `verifyPassword`, `extractAuth`, `requireRole` | All services + dashboards |
| `@bytelyst/auth-client` | Client-side auth utilities   | Token refresh, storage abstractions                                              | Web + React Native        |
| `@bytelyst/auth-ui`     | Pre-built auth UI components | Login, MFA challenge, passkey views (React)                                      | Dashboards + auth app     |
| `@bytelyst/react-auth`  | React auth context factory   | `createAuthContext()` — typed provider + hook                                    | Next.js dashboards        |

### 2.3 API & Clients

| Package                         | Purpose                               | Exports                                                                               | Consumers                     |
| ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------- |
| `@bytelyst/api-client`          | Typed fetch wrapper                   | `createApiClient()` with auth injection                                               | Web + RN                      |
| `@bytelyst/platform-client`     | Platform service client               | Typed fetch with 401 retry                                                            | Web + RN                      |
| `@bytelyst/broadcast-client`    | Broadcast/survey client               | Poll and broadcast APIs                                                               | iOS + Android                 |
| `@bytelyst/survey-client`       | Survey response client                | Submit survey responses                                                               | iOS + Android                 |
| `@bytelyst/marketplace-client`  | Marketplace listing/purchase client   | Browse, purchase, listing CRUD                                                        | Web + RN                      |
| `@bytelyst/org-client`          | Organization management client        | Org CRUD, member management                                                           | Web + RN                      |
| `@bytelyst/referral-client`     | Referral system client                | Referral creation, tracking, redemption                                               | Web + RN                      |
| `@bytelyst/subscription-client` | Subscription management client        | Plan selection, subscription lifecycle                                                | Web + RN                      |
| `@bytelyst/telemetry-client`    | Telemetry ingestion                   | `createTelemetryClient()` with batching                                               | All platforms                 |
| `@bytelyst/feature-flag-client` | Feature flag polling                  | `createFeatureFlagClient()`                                                           | All platforms                 |
| `@bytelyst/kill-switch-client`  | Kill switch check                     | `createKillSwitchClient()` (fail-open)                                                | All platforms                 |
| `@bytelyst/offline-queue`       | Persistent retry queue                | Configurable storage adapter                                                          | Web + RN                      |
| `@bytelyst/diagnostics-client`  | Admin-triggered remote debug sessions | Session polling, trace spans, breadcrumbs, network/console/error capture, batch flush | All products (web + iOS + RN) |
| `@bytelyst/feedback-client`     | In-app feedback                       | Submit feedback + attachments                                                         | iOS + Android                 |

### 2.4 Storage & Data

| Package                 | Purpose            | Exports                             | Consumers        |
| ----------------------- | ------------------ | ----------------------------------- | ---------------- |
| `@bytelyst/blob`        | Azure Blob Storage | SAS token generation, container ops | platform-service |
| `@bytelyst/blob-client` | Blob upload client | Upload via SAS tokens               | Web + RN         |
| `@bytelyst/datastore`   | Generic data store | Repository patterns                 | Services         |
| `@bytelyst/storage`     | Storage utilities  | File operations, compression        | Services         |

### 2.5 Backend Framework

| Package                       | Purpose                   | Exports                                               | Consumers            |
| ----------------------------- | ------------------------- | ----------------------------------------------------- | -------------------- |
| `@bytelyst/fastify-core`      | Service bootstrap         | `createServiceApp()`, `startService()`, Swagger UI    | All Fastify services |
| `@bytelyst/fastify-sse`       | Server-Sent Events plugin | SSE route helpers, event streaming                    | Services with SSE    |
| `@bytelyst/events`            | In-memory event bus       | `EventBus`, typed event schemas, error isolation      | platform-service     |
| `@bytelyst/event-store`       | Persistent event store    | Event append, query, replay                           | Services             |
| `@bytelyst/webhook-dispatch`  | Webhook delivery engine   | HMAC signing, retry, dispatch                         | platform-service     |
| `@bytelyst/queue`             | Job/task queue            | Queue management, workers                             | Services             |
| `@bytelyst/monitoring`        | Health checks + telemetry | Health utilities, Loki/Grafana helpers                | All services         |
| `@bytelyst/push`              | Push notification service | APNS, FCM integration                                 | platform-service     |
| `@bytelyst/backend-config`    | Shared Zod config schema  | Base config for Fastify product backends              | Product backends     |
| `@bytelyst/backend-flags`     | Feature flag registry     | In-memory feature flags for product backends          | Product backends     |
| `@bytelyst/backend-telemetry` | Telemetry event buffer    | In-memory telemetry buffer for product backends       | Product backends     |
| `@bytelyst/fastify-auth`      | JWT auth middleware       | JWT extraction + request context for product backends | Product backends     |

### 2.6 Security

| Package                   | Purpose                      | Exports                                                                                    | Consumers          |
| ------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------ | ------------------ |
| `@bytelyst/field-encrypt` | AES-256-GCM envelope encrypt | `createFieldEncryptor()`, 3 key providers (AKV, env, memory), DEK cache, migration helpers | 5 product backends |

### 2.7 AI/ML & Extraction

| Package                | Purpose                   | Exports                                             | Consumers        |
| ---------------------- | ------------------------- | --------------------------------------------------- | ---------------- |
| `@bytelyst/extraction` | Text extraction client    | `createExtractionClient()`, shared types            | Web + dashboards |
| `@bytelyst/llm`        | LLM utilities             | Prompt templates, token counting                    | Services         |
| `@bytelyst/llm-router` | Deterministic LLM routing | Provider/model selection, fallback, health tracking | Services + MCP   |
| `@bytelyst/speech`     | Speech SDK wrappers       | Azure Speech integration                            | Desktop + Mobile |

### 2.8 Platform Experience & Sync

| Package                          | Purpose                             | Exports / Surface                           | Consumers          |
| -------------------------------- | ----------------------------------- | ------------------------------------------- | ------------------ |
| `@bytelyst/dashboard-components` | Shared dashboard UI building blocks | Reusable admin/tracker UI primitives        | Dashboards         |
| `@bytelyst/dashboard-shell`      | Dashboard layout + navigation shell | Sidebar, breadcrumbs, page wrappers         | Dashboards         |
| `@bytelyst/create-app`           | App scaffolding CLI/templates       | Project generator, template engine          | New product setup  |
| `@bytelyst/sync`                 | Cross-platform sync helpers         | Sync orchestration, queueing, merge helpers | SDKs + mobile apps |
| `@bytelyst/swift-diagnostics`    | Swift diagnostics support           | Crash/error helpers, diagnostics capture    | Apple platforms    |

### 2.9 Design System & UX

| Package                          | Purpose                       | Exports                               | Consumers     |
| -------------------------------- | ----------------------------- | ------------------------------------- | ------------- |
| `@bytelyst/design-tokens`        | Cross-platform tokens         | CSS, TS, Kotlin, Swift generation     | All platforms |
| `@bytelyst/celebrations`         | Achievement/milestone effects | Confetti, toasts, celebrations        | Mobile + Web  |
| `@bytelyst/gentle-notifications` | Non-intrusive notifications   | Subtle notification patterns          | Mobile + Web  |
| `@bytelyst/quick-actions`        | Shortcut/quick-action helpers | Action registration, command palette  | Mobile + Web  |
| `@bytelyst/time-references`      | Familiar time references      | Relative time, time blindness helpers | Web + Mobile  |
| `@bytelyst/accessibility`        | Accessibility utilities       | VoiceOver, Dynamic Type, a11y checks  | All platforms |

### 2.10 React Native

| Package                               | Purpose         | Exports                                  | Consumers               |
| ------------------------------------- | --------------- | ---------------------------------------- | ----------------------- |
| `@bytelyst/react-native-platform-sdk` | RN platform SDK | Unified client for all platform features | NomGap + future RN apps |

---

## 3. Platform Services

### 3.1 platform-service (Port 4003)

Consolidated from billing-service, growth-service, tracker-service.

**Status:** Active | **Tests:** ~1,050+ | **Modules:** 63

**Route Note:** Route families below are shown in their deployed form. Most are registered under the `/api` prefix unless explicitly public.

| Module                   | Purpose                                               | Cosmos Container                                                                | Public API                               |
| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- |
| **auth**                 | JWT issue/refresh, password reset, email verification | `users`, `password_reset_tokens`, `email_verifications`                         | `/api/auth/*`                            |
| **audit**                | Audit logging                                         | `audit_log`                                                                     | Admin only                               |
| **blob**                 | Azure Blob Storage                                    | -                                                                               | `/api/blob/*`                            |
| **broadcasts**           | Feature announcements                                 | `broadcasts`                                                                    | Admin: CRUD, Public: read                |
| **comments**             | Item comments                                         | `comments`                                                                      | `/comments/*`                            |
| **delivery**             | Email/push delivery                                   | `delivery_log`, templates                                                       | Internal                                 |
| **diagnostics**          | Remote diagnostics, error clustering                  | `diagnostic_sessions`, `error_clusters`                                         | `/diagnostics/*`                         |
| **ai-diagnostics**       | AI-powered diagnostic assistant                       | `auto_triggers`, `diagnostic_sessions`                                          | `/ai-diagnostics/*`                      |
| **flags**                | Feature flags                                         | `feature_flags`                                                                 | `/flags/poll` (client)                   |
| **invitations**          | Team invitations                                      | `invitations`                                                                   | `/invitations/*`                         |
| **ip-rules**             | IP allow/deny                                         | `ip_rules`                                                                      | Admin only                               |
| **items**                | Tracker items                                         | `items`                                                                         | `/items/*`                               |
| **jobs**                 | Scheduled job runner                                  | `job_definitions`, `job_runs`                                                   | Admin only                               |
| **licenses**             | License key management                                | `licenses`                                                                      | `/licenses/*`                            |
| **maintenance**          | Maintenance mode                                      | `maintenance_windows`                                                           | Admin only                               |
| **marketplace**          | Product marketplace (JarvisJr)                        | `marketplace_listings`, `purchases`                                             | `/marketplace/*`                         |
| **notifications**        | Push/email triggers                                   | `notification_queue`                                                            | Internal                                 |
| **plans**                | Subscription plans                                    | `plans`                                                                         | `/plans/*`                               |
| **products**             | Product registry                                      | `products`                                                                      | Admin only                               |
| **promos**               | Promo codes                                           | `promos`                                                                        | `/promos/*`                              |
| **public**               | Public endpoints (no auth)                            | -                                                                               | `/public/*`                              |
| **referrals**            | Referral system                                       | `referrals`                                                                     | `/referrals/*`                           |
| **sessions**             | Device session management                             | `sessions`                                                                      | `/sessions/*`                            |
| **settings**             | Platform settings                                     | `settings`                                                                      | Admin only                               |
| **status**               | Public status page                                    | `incidents`                                                                     | `/status/*` (public read)                |
| **stripe**               | Stripe webhooks                                       | -                                                                               | `/stripe/webhook`                        |
| **subscriptions**        | Subscriptions                                         | `subscriptions`                                                                 | `/subscriptions/*`                       |
| **surveys**              | User surveys                                          | `surveys`, `survey_responses`                                                   | `/surveys/*`                             |
| **telemetry**            | Client telemetry ingestion                            | `telemetry_events`, `telemetry_error_clusters`, `telemetry_collection_policies` | `/telemetry/*`                           |
| **themes**               | Platform themes                                       | `themes`                                                                        | `/themes/*`                              |
| **tokens**               | API tokens                                            | `api_tokens`                                                                    | `/tokens/*`                              |
| **usage**                | Usage tracking                                        | `usage_daily`, `usage_hourly`                                                   | `/usage/*`                               |
| **votes**                | Item voting                                           | `votes`                                                                         | `/votes/*`                               |
| **waitlist**             | Pre-launch signup                                     | `waitlist`                                                                      | `/waitlist/*`                            |
| **webhooks**             | Webhook subscriptions                                 | `webhook_subscriptions`, `webhook_deliveries`                                   | `/webhooks/*`                            |
| **ab-testing**           | A/B experiments                                       | `experiments`, `experiment_assignments`                                         | `/api/ab-testing/*`                      |
| **predictive-analytics** | Churn/health scoring                                  | `predictive_scores`, `score_history`                                            | `/api/predictive-analytics/*`            |
| **analytics**            | Analytics rollups                                     | `analytics_events`, `analytics_aggregates`                                      | `/analytics/*`                           |
| **exports**              | GDPR data export                                      | `export_jobs`                                                                   | `/exports/*`                             |
| **feedback**             | In-app feedback                                       | `feedback`                                                                      | `/feedback/*`                            |
| **impersonation**        | User impersonation                                    | `impersonation_sessions`                                                        | `/impersonation/*`                       |
| **changelog**            | Product changelogs                                    | `changelogs`                                                                    | `/api/changelog`, `/api/admin/changelog` |
| **ratelimit**            | Rate limiting                                         | `rate_limit_windows`                                                            | `/ratelimit/*`                           |
| **agent-evals**          | Agent evaluation framework                            | `agent_evals`                                                                   | `/api/agent-evals/*`                     |
| **agents**               | Agent registry + prompt versioning                    | `agents`                                                                        | `/api/agents/*`                          |
| **ai-budgets**           | AI spend/budget governance                            | `ai_budgets`                                                                    | `/api/ai-budgets/*`                      |
| **api-versioning**       | API version management                                | `api_versions`                                                                  | `/api/api-versioning/*`                  |
| **backups**              | Backup/restore management                             | `backups`                                                                       | Admin only                               |
| **billing-checkout**     | Stripe Checkout session creation                      | —                                                                               | `/api/billing-checkout/*`                |
| **cdn**                  | CDN/asset pipeline management                         | `cdn_assets`                                                                    | `/api/cdn/*`                             |
| **dunning**              | Billing dunning/retry for failed payments             | `dunning_attempts`                                                              | Internal                                 |
| **event-subscriptions**  | Durable event bus subscriptions                       | `event_subscriptions`                                                           | `/api/event-subscriptions/*`             |
| **experiments**          | Experiment management                                 | `experiments`                                                                   | `/api/experiments/*`                     |
| **knowledge**            | Knowledge base / RAG content                          | `knowledge_articles`                                                            | `/api/knowledge/*`                       |
| **onboarding**           | User onboarding flows                                 | `onboarding_progress`                                                           | `/api/onboarding/*`                      |
| **orgs**                 | Organization/workspace management                     | `orgs`, `org_members`                                                           | `/api/orgs/*`                            |
| **retention**            | Data retention policies                               | `retention_policies`                                                            | Admin only                               |
| **reviews**              | Human review/approval queues                          | `reviews`                                                                       | `/api/reviews/*`                         |
| **runs**                 | Agent run tracking + orchestration                    | `runs`, `run_steps`                                                             | `/api/runs/*`                            |
| **scim**                 | SCIM provisioning (enterprise SSO)                    | `scim_resources`                                                                | `/scim/v2/*`                             |
| **search**               | Full-text search                                      | `search_index`                                                                  | `/api/search/*`                          |
| **support-cases**        | Support case management                               | `support_cases`                                                                 | `/api/support-cases/*`                   |
| **tenants**              | Multi-tenant isolation                                | `tenants`                                                                       | `/api/tenants/*`                         |

### 3.2 extraction-service (Port 4005)

**Status:** Active | **Tests:** 47 | **Modules:** 2

| Module      | Purpose                       | Type                       |
| ----------- | ----------------------------- | -------------------------- |
| **extract** | Text extraction (LangExtract) | Python + TypeScript hybrid |
| **tasks**   | Extraction task management    | TypeScript                 |

### 3.3 mcp-server (Port 4007 — Tooling + A2A orchestration)

**Status:** Active | **Primary Role:** Tool registry + MCP tool execution + A2A orchestration layer | **Namespaces:** 14

| Namespace / Area | Purpose                                                                                   | Surface                         |
| ---------------- | ----------------------------------------------------------------------------------------- | ------------------------------- |
| **tools**        | Tool registry, schema exposure, execution routing                                         | `/api/tools`, `/api/tools/call` |
| **platform**     | Admin/operator tools for telemetry, diagnostics, secrets, experiments, SDK, webhooks, ops | MCP tools (8 sub-modules)       |
| **extraction**   | MCP wrappers for extraction workflows                                                     | MCP tools                       |
| **a2a**          | Cross-product agent-to-agent pipelines and orchestration flows                            | Pipeline tools (38 items)       |
| **dev**          | Changelog generation, synthetic data generation, internal dev tooling                     | MCP tools                       |
| **support**      | Support case tools                                                                        | MCP tools                       |
| **notes**        | NoteLett-specific MCP tools                                                               | MCP tools                       |
| **lysnrai**      | LysnrAI product tools                                                                     | MCP tools                       |
| **jarvis**       | JarvisJr product tools                                                                    | MCP tools                       |
| **chronomind**   | ChronoMind product tools                                                                  | MCP tools                       |
| **nomgap**       | NomGap product tools                                                                      | MCP tools                       |
| **peakpulse**    | PeakPulse product tools                                                                   | MCP tools                       |
| **mindlyst**     | MindLyst product tools                                                                    | MCP tools                       |
| **tracker**      | Tracker product tools                                                                     | MCP tools                       |

### 3.4 monitoring

| Component        | Purpose                            | Surface            |
| ---------------- | ---------------------------------- | ------------------ |
| **health-check** | Local service health aggregation   | CLI / script       |
| **loki**         | Structured log aggregation         | Docker/local infra |
| **grafana**      | Dashboards and observability views | Docker/local infra |

---

## 4. Dashboards (Product-Agnostic)

### 4.1 admin-web (Port 3001)

**Stack:** Next.js 16 + React 19 + TailwindCSS v4 + shadcn/ui

| Feature            | Path               | Description                      |
| ------------------ | ------------------ | -------------------------------- |
| Mission Control    | `/ops`             | Service health dashboard         |
| Secrets Manager    | `/ops/secrets`     | Azure Key Vault CRUD             |
| Client Logs        | `/ops/client-logs` | Telemetry query + error clusters |
| User Management    | `/users`           | CRUD, roles, sessions            |
| License Management | `/licenses`        | Key generation, tracking         |
| Usage Analytics    | `/usage`           | Daily/hourly metrics             |
| API Tokens         | `/tokens`          | Admin token management           |
| Broadcasts         | `/broadcasts`      | Feature announcements            |
| Themes             | `/themes`          | Platform theme editor            |
| Feature Flags      | `/flags`           | Flag management + rollout        |

**Key Files:**

- `src/lib/cosmos.ts` — Cosmos client
- `src/lib/auth-server.ts` — JWT + bcrypt
- `src/lib/product-config.ts` — Product identity
- `src/lib/platform-client.ts` — platform-service client
- `src/lib/telemetry-client.ts` — telemetry query client

### 4.2 tracker-web (Port 3003)

**Stack:** Next.js 16 + React 19 + TailwindCSS v4

| Feature        | Path         | Description               |
| -------------- | ------------ | ------------------------- |
| Public Roadmap | `/roadmap`   | Feature requests + voting |
| Item Detail    | `/items/:id` | Discussion + voting       |
| Submit         | `/submit`    | New feature request       |

### 4.3 ux-lab

**Stack:** Experimental/internal dashboard workbench for operations UI kits, scoped prototypes, and MCP-driven UX workflows.

| Area                                | Description                                             |
| ----------------------------------- | ------------------------------------------------------- |
| `bolt-command-palette-kit/`         | Command palette UX prototype                            |
| `bolt-ops-ui-kit/`                  | Internal UI kit and scoping docs for ops/dashboard work |
| `bolt-telemetry-explorer/`          | Telemetry data exploration prototype                    |
| `bolt-timeline-studio/`             | Timeline visualization prototype                        |
| `lovable-design-tokens-playground/` | Design token preview/playground                         |
| `lovable-notify-states-kit/`        | Notification state patterns prototype                   |
| `lovable-onboarding-flow/`          | Onboarding flow UX prototype                            |
| `lovable-settings-ux-kit/`          | Settings page UX patterns prototype                     |

---

## 5. Platform SDKs

### 5.1 Swift Platform SDK (`packages/swift-platform-sdk/`)

**Components:** 20 | **Language:** Swift 5.9+ | **Platforms:** iOS 17+, watchOS 10+, macOS 14+

| Component             | Purpose                                                          |
| --------------------- | ---------------------------------------------------------------- |
| `BLPlatformConfig`    | Product configuration (productId, baseURL, bundleId, appGroupId) |
| `BLPlatformClient`    | Generic HTTP client (auth injection, x-request-id, timeout)      |
| `BLKeychain`          | Keychain CRUD                                                    |
| `BLAuthClient`        | Full auth (login, register, refresh, password ops)               |
| `BLTelemetryClient`   | Telemetry queue + batch flush                                    |
| `BLFeatureFlagClient` | Feature flag polling                                             |
| `BLSyncEngine`        | Generic offline-first sync                                       |
| `BLBlobClient`        | Blob upload via SAS tokens                                       |
| `BLKillSwitchClient`  | Kill switch check (fail-open)                                    |
| `BLLicenseClient`     | License activation + status                                      |
| `BLBiometricAuth`     | Face ID / Touch ID                                               |
| `BLCrashReporter`     | MetricKit crash reporting                                        |
| `BLAuditLogger`       | Local rotating JSON audit log                                    |
| `BLFeedbackClient`    | In-app feedback submission                                       |
| `BLSurveyClient`      | Survey polling + response                                        |
| `BLDeepLinkRouter`    | Deep link handling                                               |
| `BLInAppMessageUI`    | In-app message display                                           |
| `BLSurveyUI`          | Survey UI components                                             |
| `ByteLystPlatformSDK` | Umbrella export                                                  |

**Migrated Apps:** LysnrAI, ChronoMind, MindLyst, PeakPulse, JarvisJr

### 5.2 Kotlin Platform SDK (`packages/kotlin-platform-sdk/`)

**Components:** 18 | **Language:** Kotlin 2.0+ | **Platforms:** Android (minSdk 26)

| Component             | Purpose                                  |
| --------------------- | ---------------------------------------- |
| `BLPlatformConfig`    | Product configuration                    |
| `BLPlatformClient`    | OkHttp-based HTTP client                 |
| `BLSecureStore`       | EncryptedSharedPreferences wrapper       |
| `BLAuthClient`        | Full auth + token management + StateFlow |
| `BLTelemetryClient`   | Batched events + SharedPreferences queue |
| `BLFeatureFlagClient` | Feature flag polling                     |
| `BLKillSwitchClient`  | Kill switch (fail-open)                  |
| `BLBlobClient`        | SAS upload                               |
| `BLLicenseClient`     | License activation                       |
| `BLAuditLogger`       | Rotating JSONL audit log                 |
| `BLBiometricAuth`     | AndroidX BiometricPrompt                 |
| `BLCrashReporter`     | UncaughtExceptionHandler                 |
| `BLSyncEngine`        | Pull-merge-push sync                     |
| `BLFeedbackClient`    | Feedback submission                      |
| `BLSurveyClient`      | Survey polling                           |
| `BLBroadcastClient`   | Broadcast/announcement                   |
| `DeepLinkRouter`      | Deep link handling                       |

**Migrated Apps:** ChronoMind, MindLyst, LysnrAI (all via Gradle `includeBuild`)

**Tests:** 35 JUnit5 + MockWebServer

### 5.3 React Native Platform SDK (`packages/react-native-platform-sdk/`)

**Components:** Unified client | **Platforms:** iOS, Android (React Native / Expo)

| Component       | Purpose                               |
| --------------- | ------------------------------------- |
| Platform Client | Unified API for all platform features |
| Auth            | Token management                      |
| Telemetry       | Event batching                        |
| Feature Flags   | Polling client                        |
| Kill Switch     | Fail-open check                       |
| Offline Queue   | Persistent retry                      |

**Migrated Apps:** NomGap

---

## 6. AI.dev Skills (`.windsurf/workflows/`)

Workflow scripts for AI agents and developers:

| Workflow                   | Purpose                                |
| -------------------------- | -------------------------------------- |
| `README.md`                | Skills directory overview              |
| `architecture-patterns.md` | Common architectural patterns          |
| `backup-main-branch.md`    | Smart backup with duplicate detection  |
| `debug-service.md`         | Debug failing services                 |
| `desktop-release.md`       | Build and release desktop apps         |
| `docker-compose.md`        | Run all services via Docker            |
| `dual-network-setup.md`    | Corporate proxy + home network         |
| `generate-store-assets.md` | App store artwork (icons, screenshots) |
| `index.md`                 | Workflow index                         |
| `ios-release.md`           | Build and release iOS apps             |
| `local-development.md`     | Local dev setup                        |
| `mobile-code-quality.md`   | iOS/Android quality checks             |
| `production-readiness.md`  | Pre-release checklist                  |
| `scan-repo-context.md`     | Update WINDSURF_CONTEXT.md             |
| `security-auditing.md`     | Security audit procedures              |
| `test-desktop-app.md`      | Desktop app testing                    |
| `test-ios-app.md`          | iOS testing in Simulator               |
| `test-strategies.md`       | Testing patterns                       |
| `agent-behavior-guidelines.md` | Canonical agent behavior rules (Karpathy + ByteLyst) |
| `agent-onboarding.md`      | Read-order index for agents            |

---

## 7. Scripts (`scripts/`)

| Script                        | Purpose                                      |
| ----------------------------- | -------------------------------------------- |
| `backup-main.sh`              | Backup main branches across repos            |
| `check-prototype-env.sh`      | Validate prototype environment vars          |
| `cosmos-telemetry-indexes.sh` | Create Cosmos indexes for telemetry          |
| `docker-prep.sh`              | Prepare for Docker builds                    |
| `export-lysnr-kv.sh`          | Export LysnrAI Key Vault secrets             |
| `prep-consumer.sh`            | Prepare consumer builds                      |
| `prototype-self-test.sh`      | Host-side prototype smoke test               |
| `prototype-up.sh`             | Start prototype Docker stack                 |
| `secret-scan-repo.sh`         | Scan repo for secrets                        |
| `secret-scan-staged.sh`       | Scan staged files                            |
| `seed-keyvault.sh`            | Seed Key Vault with required secrets         |
| `seed-lysnr-kv.sh`            | Seed LysnrAI Key Vault                       |
| `setup-husky.sh`              | Setup Git hooks                              |
| `switch-network.sh`           | Switch between corporate/home network        |
| `sync-workflows.sh`           | Sync workflows across repos                  |
| `update-agent-docs.sh`        | Regenerate AGENTS.md pointer + derived files across repos |
| `check-agent-docs-drift.sh`   | Verify single-source-of-truth invariants (CI gate) |

---

## 8. Product Configurations (`products/`)

Each product has a `product.json` manifest:

| Product    | File                      | Backend Port | Repo                                | Encrypted |
| ---------- | ------------------------- | ------------ | ----------------------------------- | --------- |
| LysnrAI    | `lysnrai/product.json`    | 4015         | `learning_voice_ai_agent`           | ✅        |
| MindLyst   | `mindlyst/product.json`   | 4014         | `learning_multimodal_memory_agents` | —         |
| ChronoMind | `chronomind/product.json` | 4011         | `learning_ai_clock`                 | —         |
| JarvisJr   | `jarvisjr/product.json`   | 4012         | `learning_ai_jarvis_jr`             | ✅        |
| NomGap     | `nomgap/product.json`     | 4013         | `learning_ai_fastgap`               | ✅        |
| PeakPulse  | `peakpulse/product.json`  | 4010         | `learning_ai_peakpulse`             | —         |
| NoteLett   | `notelett/product.json`   | 4016         | `learning_ai_notes`                 | ✅        |

---

## 9. Completed Roadmaps (`docs/roadmaps/completed/`)

| Roadmap                                      | Description                          |
| -------------------------------------------- | ------------------------------------ |
| `cloud_AGNOSTIC_REFACTOR_ROADMAP.md`         | Cloud-agnostic infrastructure        |
| `cloud_REFERRALS_PARTITION_KEY_MIGRATION.md` | Cosmos partition key migration       |
| `diagnostics_REMOTE_DIAGNOSTICS_ROADMAP.md`  | Remote diagnostics system            |
| `extraction_SERVICE_ROADMAP.md`              | Text extraction service              |
| `mobile_ANDROID_PLATFORM_SDK.md`             | Android SDK design                   |
| `mobile_IOS_PLATFORM_SDK.md`                 | iOS SDK design                       |
| `mobile_REACT_NATIVE_PLATFORM_SDK.md`        | React Native SDK design              |
| `platform_ACCELERATION_ROADMAP.md`           | Platform acceleration initiatives    |
| `platform_BACKEND_MIGRATION.md`              | Backend consolidation                |
| `platform_BROADCAST_SURVEY_ROADMAP.md`       | Broadcast + survey system            |
| `platform_COMMON_EXTRACTION_ROADMAP.md`      | Shared extraction                    |
| `platform_COMPONENTS_ROADMAP.md`             | Platform components (23 of 25 built) |
| `platform_SERVICE_CONSOLIDATION_ROADMAP.md`  | Service merger (4001→4003)           |
| `product_MARKETPLACE_MODULE_DESIGN.md`       | JarvisJr marketplace                 |
| `product_PRE_LAUNCH_SIGNUP_SYSTEM.md`        | Waitlist system                      |
| `telemetry_IMPLEMENTATION_ROADMAP.md`        | Client telemetry                     |

---

## 10. Active/Planned Roadmaps (`docs/roadmaps/`)

### 10.1 Active Roadmaps

| Roadmap                                      | Status      |
| -------------------------------------------- | ----------- |
| `AI_DIAGNOSTIC_ASSISTANT_ROADMAP.md`         | In Progress |
| `INTELLIGENT_AB_TESTING_ROADMAP.md`          | Active      |
| `P3_PLATFORM_DEEPENING_ROADMAP.md`           | Active      |
| `PREDICTIVE_CHURN_HEALTH_SCORING_ROADMAP.md` | Active      |
| `SHARED_CLIENT_PACKAGES_ROADMAP.md`          | Active      |
| `WORKSPACE_REVIEW_2026_03_19.md`             | Active      |

### 10.2 Scaffolded Roadmaps (`docs/roadmaps/scaffolded/`)

| Roadmap                                                    | Focus Area                         |
| ---------------------------------------------------------- | ---------------------------------- |
| `platform_AGENT_REGISTRY_PROMPT_VERSIONING_ROADMAP.md`     | Agent registry + prompt versioning |
| `platform_AGENT_RUNTIME_ORCHESTRATION_ROADMAP.md`          | Agent runtime orchestration        |
| `platform_AI_BUDGET_COST_GOVERNANCE_ROADMAP.md`            | AI spend/budget governance         |
| `platform_AI_GOVERNANCE_EVALS_ROADMAP.md`                  | AI governance + evaluations        |
| `platform_DURABLE_EVENT_BUS_AND_WORKER_RUNTIME_ROADMAP.md` | Durable event bus + worker runtime |
| `platform_ENTERPRISE_PROVISIONING_SCIM_ROADMAP.md`         | Enterprise SCIM provisioning       |
| `platform_HUMAN_REVIEW_APPROVAL_QUEUE_ROADMAP.md`          | Human review/approval queues       |
| `platform_KNOWLEDGE_RAG_SERVICE_ROADMAP.md`                | Knowledge base / RAG service       |
| `platform_ORG_WORKSPACE_RBAC_ROADMAP.md`                   | Org/workspace RBAC                 |
| `platform_SUPPORT_CASE_MANAGEMENT_ROADMAP.md`              | Support case management            |

### 10.3 Not Started

| Roadmap                                        | Focus Area                        |
| ---------------------------------------------- | --------------------------------- |
| `platform_AGENT_PLATFORM_GAP_ROADMAP_INDEX.md` | Agent platform gap analysis index |

---

## 11. Documentation Directory (`docs/`)

| Subdirectory / File                    | Purpose                                                                                     |
| -------------------------------------- | ------------------------------------------------------------------------------------------- |
| `architecture/`                        | Ecosystem architecture, cloud migration analysis                                            |
| `audits/`                              | Security audit, auth analysis, Fastify-core audit, FlowMonk audit                           |
| `design/`                              | Agent prompts sync, client telemetry design, cross-product dashboard                        |
| `design-system/`                       | Design system documentation                                                                 |
| `devops/`                              | Azure portal/resource/KV setup, single-VM deployment docs, env audit, diagnostics           |
| `guides/`                              | Migration guide, platform playbook, workflow sync, anti-patterns                            |
| `MCP+A2A/`                             | MCP server framework, A2A orchestration, domain docs, execution checklist, use-case catalog |
| `roadmaps/`                            | 16 completed, 6 active, 10 scaffolded, 1 not-started                                        |
| `session-logs/`                        | Session history logs                                                                        |
| `workstreams/`                         | Active workstream tracking                                                                  |
| `BROADCAST_SURVEY_API_REFERENCE.md`    | Broadcast + survey API reference                                                            |
| `PROTOTYPE_DEPLOYMENT.md`              | Prototype deployment guide                                                                  |
| `WORKSPACE_INVENTORY.md`               | Workspace-level inventory (this repo + all products)                                        |
| `learning_ai_common_plat_INVENTORY.md` | This file — common-plat repo inventory                                                      |

---

## 12. Local LLMs Infrastructure (`__LOCAL_LLMs/`)

| Area                     | Purpose                                             |
| ------------------------ | --------------------------------------------------- |
| `dashboard/`             | Next.js local LLM dashboard (Ollama chat UI)        |
| `AI_IDE_CHAT_HISTORY/`   | Windsurf chat history archive                       |
| `OPEN_CLAW/`             | Personal AI assistant prototype                     |
| `VOICEBOX/`              | Local TTS/voice setup                               |
| `oss_llm/`               | Open-source LLM experiments (nanoGPT, model search) |
| `windows_specific/`      | Windows-specific LLM setup scripts                  |
| `setup-tts.sh`           | One-shot TTS model setup                            |
| `download-tts-models.sh` | Model weight downloader (hf-mirror for corp proxy)  |
| `start-dashboard.sh`     | Start local LLM dashboard                           |

---

## 13. How to Consume

### 13.1 TypeScript Packages (Services/Dashboards)

```json
// package.json
{
  "dependencies": {
    "@bytelyst/cosmos": "file:../learning_ai_common_plat/packages/cosmos",
    "@bytelyst/auth": "file:../learning_ai_common_plat/packages/auth",
    "@bytelyst/config": "file:../learning_ai_common_plat/packages/config"
  }
}
```

```typescript
// In code
import { getCosmosClient, registerContainers } from '@bytelyst/cosmos';
import { createJwtUtils } from '@bytelyst/auth';
import { loadProductIdentity } from '@bytelyst/config';
```

### 13.2 Swift SDK (iOS)

```swift
// Package.swift
dependencies: [
    .package(path: "../learning_ai_common_plat/packages/swift-platform-sdk")
]

// In code
import ByteLystPlatformSDK
let config = BLPlatformConfig(productId: "myproduct", baseURL: "...")
```

### 13.3 Kotlin SDK (Android)

```kotlin
// settings.gradle.kts
includeBuild("../learning_ai_common_plat/packages/kotlin-platform-sdk")

// build.gradle.kts
implementation("com.bytelyst:platform-sdk:1.0.0")

// In code
import com.bytelyst.platform.BLPlatformConfig
val config = BLPlatformConfig(productId = "myproduct", baseURL = "...")
```

### 13.4 React Native SDK

```json
// package.json
{
  "dependencies": {
    "@bytelyst/react-native-platform-sdk": "file:../learning_ai_common_plat/packages/react-native-platform-sdk"
  }
}
```

---

## 14. Build Verification Commands

```bash
# Full platform build
pnpm build

# Full test suite
pnpm test

# Type check
pnpm typecheck

# Individual service
pnpm --filter @lysnrai/platform-service test

# Swift SDK
cd packages/swift-platform-sdk && swift build

# Kotlin SDK
cd packages/kotlin-platform-sdk && ./gradlew build

# Dashboards
cd dashboards/admin-web && npm run build
cd dashboards/tracker-web && npm run build
```

---

## 15. Architecture Diagram

```
┌──────────────────────────────────────────────────────────────────────────┐
│                           PRODUCT APPS (10)                              │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐          │
│  │LysnrAI  │ │MindLyst │ │ChronoM. │ │JarvisJr │ │NomGap   │          │
│  │ :4015   │ │ :4014   │ │ :4011   │ │ :4012   │ │ :4013   │          │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘          │
│  ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐          │
│  │PeakPulse│ │NoteLett │ │FlowMonk │ │Action   │ │LocalMem │          │
│  │ :4010   │ │ :4016   │ │ :4017   │ │Trail    │ │GPT:4019 │          │
│  │         │ │         │ │         │ │ :4018   │ │(standal)│          │
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘          │
│       └───────────┴───────────┴───────────┴───────────┘                │
│                         │                                              │
│              ┌──────────┴──────────┐                                   │
│              │  Platform SDKs (3)  │                                   │
│              │  Swift/Kotlin/RN    │                                   │
│              └──────────┬──────────┘                                   │
└─────────────────────────┼────────────────────────────────────────────────┘
                          │
┌─────────────────────────┼────────────────────────────────────────────────┐
│              ┌──────────┴──────────┐                                    │
│              │ Shared Packages (58)│                                    │
│              │  (@bytelyst/*)      │                                    │
│              └──────────┬──────────┘                                    │
│                         │                                              │
│  ┌──────────────────────┼──────────────────────────────────────────┐   │
│  │         platform-service (4003) — 63 modules                   │   │
│  │  auth │ flags │ telemetry │ blob │ orgs │ billing │ etc.      │   │
│  └──────────────────────┬──────────────────────────────────────────┘   │
│                         │                                              │
│  ┌──────────────────────┼──────────────────────────────────────────┐   │
│  │      extraction-service (4005)     │     mcp-server (4007)     │   │
│  │      Text extraction (LangExtract) │  MCP tools + A2A (14 ns) │   │
│  └──────────────────────┬──────────────────────────────────────────┘   │
│                         │                                              │
│              ┌──────────┴──────────┐                                   │
│              │  Azure Cosmos DB    │                                   │
│              │  Azure Blob Storage │                                   │
│              │  Azure Key Vault    │                                   │
│              └─────────────────────┘                                   │
└───────────────────────────────────────────────────────────────────────────┘
```

---

## 16. Contact & Contribution

- **Primary Repo:** `learning_ai_common_plat`
- **Package Scope:** `@bytelyst/*`
- **Service Scope:** `@lysnrai/*`
- **New Components:** Follow existing patterns in `types.ts` → `repository.ts` → `routes.ts`
- **Tests Required:** All new code must have tests (Vitest for TS, XCTest for Swift, JUnit5 for Kotlin)
