learning_ai_common_plat/docs/learning_ai_common_plat_INVENTORY.md

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

---

1. Quick Stats

Category	Count	Notes
Shared Packages	36	@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
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 Platform Experience & Sync

Package	Purpose	Exports / Surface	Consumers
@bytelyst/dashboard-components	Shared dashboard UI building blocks	Reusable admin/tracker UI primitives	Dashboards
@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.8 Design System

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

2.9 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

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

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 (Tooling + A2A orchestration)

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

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
extraction	MCP wrappers for extraction workflows	MCP tools
a2a	Cross-product agent-to-agent pipelines and orchestration flows	Pipeline tools
dev	Changelog generation, synthetic data generation, internal dev tooling	MCP tools
product namespaces	Product-specific tool entry points for LysnrAI, JarvisJr, ChronoMind, NomGap, PeakPulse, MindLyst, tracker	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-ops-ui-kit/	Internal UI kit and scoping docs for ops/dashboard work
Prototypes	Workspace for UX exploration, MCP-assisted workflows, and internal experimentation

---

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)

// 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"
  }
}

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

11.2 Swift SDK (iOS)

// 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)

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

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

---

12. Build Verification Commands

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