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

---

## 1. Quick Stats

| Category              | Count   | Notes                                                 |
| --------------------- | ------- | ----------------------------------------------------- |
| **Shared Packages**   | 32      | `@bytelyst/*` — consumed via `file:` or `workspace:*` |
| **Platform Services** | 2       | Running services (consolidated from 5)                |
| **Dashboards**        | 2       | Product-agnostic web consoles                         |
| **Platform SDKs**     | 3       | Swift, Kotlin, React Native                           |
| **Cosmos Containers** | ~50+    | Shared + product-specific                             |
| **Total Tests**       | ~1,700+ | Service + package + SDK tests                         |

---

## 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/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/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 6 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/events`       | In-memory event bus       | `EventBus`, typed event schemas, error isolation   | platform-service     |
| `@bytelyst/monitoring`   | Health checks + telemetry | Health utilities, Loki/Grafana helpers             | All services         |
| `@bytelyst/push`         | Push notification service | APNS, FCM integration                              | platform-service     |

### 2.6 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/speech`     | Speech SDK wrappers    | Azure Speech integration                 | Desktop + Mobile |

### 2.7 Design System

| Package                   | Purpose               | Exports                           | Consumers     |
| ------------------------- | --------------------- | --------------------------------- | ------------- |
| `@bytelyst/design-tokens` | Cross-platform tokens | CSS, TS, Kotlin, Swift generation | All platforms |

### 2.8 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:** 45

| Module                   | Purpose                                               | Cosmos Container                                                                | Public API                |
| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------- |
| **auth**                 | JWT issue/refresh, password reset, email verification | `users`, `password_reset_tokens`, `email_verifications`                         | `/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`                                         | `/experiments/*`          |
| **predictive-analytics** | Churn/health scoring                                  | `predictive_scores`, `score_history`                                            | `/predictive/*`           |
| **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`                                                                    | `/changelogs/*`           |
| **ratelimit**            | Rate limiting                                         | `rate_limit_windows`                                                            | `/ratelimit/*`            |

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

---

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

---

## 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                                |
| -------------------------- | -------------------------------------- |
| `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                       |
| `update-agent-docs.md`     | Regenerate AGENTS.md, CLAUDE.md, etc.  |

---

## 7. Scripts (`scripts/`)

| Script                        | Purpose                               |
| ----------------------------- | ------------------------------------- |
| `backup-main.sh`              | Backup main branches across repos     |
| `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               |
| `railway-deploy.sh`           | Deploy to Railway                     |
| `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.md`           | Sync workflows across repos           |

---

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

Each product has a `product.json` manifest:

| Product    | File                      | Backend Port |
| ---------- | ------------------------- | ------------ |
| LysnrAI    | `lysnrai/product.json`    | 4015         |
| MindLyst   | `mindlyst/product.json`   | 4014         |
| ChronoMind | `chronomind/product.json` | 4011         |
| JarvisJr   | `jarvisjr/product.json`   | 4012         |
| NomGap     | `nomgap/product.json`     | 4013         |
| PeakPulse  | `peakpulse/product.json`  | 4010         |

---

## 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_BACKEND_MIGRATION.md`              | Backend consolidation                |
| `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/`)

| Roadmap                                      | Status      |
| -------------------------------------------- | ----------- |
| `AI_DIAGNOSTIC_ASSISTANT_ROADMAP.md`         | In Progress |
| `INTELLIGENT_AB_TESTING_ROADMAP.md`          | Active      |
| `PREDICTIVE_CHURN_HEALTH_SCORING_ROADMAP.md` | Active      |
| `WORKSPACE_REVIEW_2026_03_03.md`             | Active      |

---

## 11. How to Consume

### 11.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';
```

### 11.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: "...")
```

### 11.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 = "...")
```

### 11.4 React Native SDK

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

---

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

---

## 13. Architecture Diagram

```
┌─────────────────────────────────────────────────────────────┐
│                     PRODUCT APPS                            │
│  ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐│
│  │LysnrAI  │ │MindLyst │ │ChronoM. │ │JarvisJr │ │NomGap   ││
│  │PeakPulse│ │         │ │         │ │         │ │         ││
│  └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘│
│       │           │           │           │           │     │
│       └───────────┴───────────┴───────────┴───────────┘     │
│                         │                                   │
│              ┌──────────┴──────────┐                       │
│              │   Platform SDKs       │                       │
│              │  (Swift/Kotlin/RN)   │                       │
│              └──────────┬──────────┘                       │
└─────────────────────────┼───────────────────────────────────┘
                          │
┌─────────────────────────┼───────────────────────────────────┐
│              ┌──────────┴──────────┐                       │
│              │   Shared Packages     │                       │
│              │  (@bytelyst/*)        │                       │
│              └──────────┬──────────┘                       │
│                         │                                   │
│  ┌──────────────────────┼────────────────────────────────┐ │
│  │           platform-service (4003)                   │ │
│  │  auth │ billing │ flags │ telemetry │ blob │ etc.  │ │
│  └──────────────────────┬────────────────────────────────┘ │
│                         │                                   │
│  ┌──────────────────────┼────────────────────────────────┐ │
│  │        extraction-service (4005)                    │ │
│  │           Text extraction (LangExtract)             │ │
│  └──────────────────────┬────────────────────────────────┘ │
│                         │                                   │
│              ┌──────────┴──────────┐                       │
│              │   Azure Cosmos DB     │                       │
│              │   Azure Blob Storage   │                       │
│              │   Azure Key Vault      │                       │
│              └───────────────────────┘                       │
└─────────────────────────────────────────────────────────────┘
```

---

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