# 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 | | `update-agent-docs.md` | Regenerate AGENTS.md, CLAUDE.md, etc. | --- ## 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 | | `railway-deploy.sh` | Deploy to Railway | | `railway-sync-env.sh` | Sync env vars 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.sh` | Sync workflows across repos | | `update-agent-docs.sh` | Regenerate AGENTS.md, CLAUDE.md across repos | --- ## 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, Railway runbook, 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)