bytelyst/learning_ai_common_plat
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(telemetry-client,diagnostics-client): add createWebTelemetry + createWebDiagnostics convenience factories

Browse Source 
- telemetry-client: createWebTelemetry() wraps createTelemetryClient() with web defaults
- diagnostics-client: createWebDiagnostics() wraps DiagnosticsClient with install ID + web defaults
- Eliminates ~70 lines of boilerplate per web app
- 11/11 telemetry tests pass, 21/21 diagnostics tests pass
This commit is contained in:
saravanakumardb1 2026-03-20 18:47:18 -07:00
parent 470661e274
commit b9e37bb8b4
7 changed files with 526 additions and 182 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
__LOCAL_LLMs/AI_IDE_CHAT_HISTORY/WINDSURF/.last-refresh.log
View File

@ -1,9 +1,9 @@
Last refresh: 2026-03-20T06:00:09Z (2026-03-19 23:00:09 PDT) Last refresh: 2026-03-21T00:06:30Z (2026-03-20 17:06:30 PDT)
Cascade conversations: 50 (381M) Cascade conversations: 50 (409M)
Memories: 89 Memories: 91
Implicit context: 20 Implicit context: 20
Code tracker dirs: 90 Code tracker dirs: 100
File edit history: 3209 entries File edit history: 3324 entries
Workspace storage: 34 workspaces Workspace storage: 36 workspaces
Repo docs: 7 files across 2 repos Repo docs: 7 files across 2 repos
Repo workflows: 43 files across 10 repos Repo workflows: 43 files across 10 repos

100
docs/WORKSPACE_INVENTORY.md
View File

@ -3,23 +3,28 @@
> **Purpose:** Workspace-level inventory for the active multi-repo ByteLyst development environment. > **Purpose:** Workspace-level inventory for the active multi-repo ByteLyst development environment.
> **Workspace Root:** `~/code/mygh/` > **Workspace Root:** `~/code/mygh/`
> **Canonical Repo List:** `.windsurf/workflows/repos.txt` > **Canonical Repo List:** `.windsurf/workflows/repos.txt`
> **Last Updated:** 2026-03-11 > **Last Updated:** 2026-03-20
--- ---
## 1. Active Workspace Repositories ## 1. Active Workspace Repositories
| Repository | Product / Role | Primary Stack | Current Scope | | Repository | Product / Role | Primary Stack | Current Scope |
| ----------------------------------- | --------------- | ------------------------------------------------------- | ------------------------------------------------------------------- | | ----------------------------------- | ------------------ | ------------------------------------------------------- | ------------------------------------------------------------------- |
| `learning_ai_common_plat` | Shared platform | TypeScript, Fastify, Next.js, Swift, Kotlin | 36 shared packages, 4 services, 3 dashboards, MCP/A2A orchestration | | `learning_ai_common_plat` | Shared platform | TypeScript, Fastify, Next.js, Swift, Kotlin | 53 shared packages, 4 services, 3 dashboards, MCP/A2A orchestration |
| `learning_voice_ai_agent` | LysnrAI | Python 3.12, Fastify, Next.js, Swift, Kotlin | Desktop app, product backend, user dashboard, mobile apps | | `learning_voice_ai_agent` | LysnrAI | Python 3.12, Fastify, Next.js, Swift, Kotlin | Desktop app, product backend, user dashboard, mobile apps |
| `learning_multimodal_memory_agents` | MindLyst | Kotlin Multiplatform, SwiftUI, Jetpack Compose, Next.js | Shared KMP core, iOS, Android, web dashboard | | `learning_multimodal_memory_agents` | MindLyst | Kotlin Multiplatform, SwiftUI, Jetpack Compose, Next.js | Shared KMP core, iOS, Android, web dashboard, product backend |
| `learning_ai_clock` | ChronoMind | Next.js, SwiftUI, Kotlin, Fastify | Timer/focus product across web, Apple, Android, backend | | `learning_ai_clock` | ChronoMind | Next.js, SwiftUI, Kotlin, Fastify | Timer/focus product across web, Apple, Android, backend |
| `learning_ai_fastgap` | NomGap | React Native (Expo), Fastify | Fasting engine, mobile UI, product backend | | `learning_ai_fastgap` | NomGap | React Native (Expo), Next.js, Fastify | Fasting engine, mobile UI, web app, product backend |
| `learning_ai_jarvis_jr` | JarvisJr | SwiftUI, Next.js, Kotlin, Fastify | Voice-first coaching apps, marketplace/backend | | `learning_ai_jarvis_jr` | JarvisJr | SwiftUI, Next.js, Kotlin, Fastify | Voice-first coaching apps, marketplace/backend |
| `learning_ai_peakpulse` | PeakPulse | SwiftUI, Fastify | Sensor-driven tracking app and backend | | `learning_ai_peakpulse` | PeakPulse | SwiftUI, Fastify | Sensor-driven tracking app and backend |
| `learning_ai_notes` | NoteLett | Fastify, Next.js, React Native (Expo) | Structured notes platform across backend, web, and mobile | | `learning_ai_notes` | NoteLett | Fastify, Next.js, React Native (Expo) | Structured notes platform across backend, web, and mobile |
| `learning_ai_flowmonk` | FlowMonk | Fastify, Next.js, React Native (Expo) | Agent-first planning platform across backend, web, and mobile | | `learning_ai_flowmonk` | FlowMonk | Fastify, Next.js, React Native (Expo) | Agent-first planning platform across backend, web, and mobile |
| `learning_ai_trails` | ActionTrail | Fastify, Next.js | AI activity oversight: actions, alerts, approvals, SDK |
| `learning_ai_smart_auth` | SmartAuth | Docs + extends platform-service | Unified auth & identity design (OneAuth, OAuth, MFA, Passkeys) |
| `learning_ai_auth_app` | ByteLyst Auth App | SwiftUI, Jetpack Compose | Standalone auth companion app (iOS, Android, watchOS, widgets) |
| `learning_ai_productivity_web` | Productivity Tools | Next.js | Internal productivity web tools |
| `learning_ai_local_memory_gpt` | LocalMemoryGPT | React, Express | Local memory-augmented GPT prototype |
--- ---
@ -27,25 +32,29 @@
`learning_ai_common_plat` is the shared infrastructure layer for the whole workspace. `learning_ai_common_plat` is the shared infrastructure layer for the whole workspace.
### 2.1 Shared Packages ### 2.1 Shared Packages (53 total)
- `@bytelyst/config`, `@bytelyst/cosmos`, `@bytelyst/errors`, `@bytelyst/logger`, `@bytelyst/testing` - **Core:** `config`, `cosmos`, `errors`, `logger`, `testing`, `datastore`, `storage`
- `@bytelyst/auth`, `@bytelyst/auth-client`, `@bytelyst/api-client`, `@bytelyst/platform-client`, `@bytelyst/react-auth` - **Auth:** `auth`, `auth-client`, `auth-ui`, `react-auth`
- `@bytelyst/blob`, `@bytelyst/blob-client`, `@bytelyst/datastore`, `@bytelyst/storage`, `@bytelyst/sync`, `@bytelyst/offline-queue` - **API/Clients:** `api-client`, `platform-client`, `broadcast-client`, `survey-client`, `feedback-client`, `marketplace-client`, `org-client`, `referral-client`, `subscription-client`
- `@bytelyst/telemetry-client`, `@bytelyst/diagnostics-client`, `@bytelyst/swift-diagnostics` - **Telemetry/Diagnostics:** `telemetry-client`, `diagnostics-client`, `swift-diagnostics`
- `@bytelyst/feature-flag-client`, `@bytelyst/feedback-client`, `@bytelyst/broadcast-client`, `@bytelyst/survey-client`, `@bytelyst/kill-switch-client` - **Feature Control:** `feature-flag-client`, `kill-switch-client`
- `@bytelyst/design-tokens`, `@bytelyst/dashboard-components` - **Storage/Data:** `blob`, `blob-client`, `sync`, `offline-queue`
- `@bytelyst/extraction`, `@bytelyst/llm`, `@bytelyst/speech` - **Backend Framework:** `fastify-core`, `fastify-sse`, `events`, `event-store`, `monitoring`, `push`, `queue`, `webhook-dispatch`
- `@bytelyst/swift-platform-sdk`, `@bytelyst/kotlin-platform-sdk`, `@bytelyst/react-native-platform-sdk` - **AI/ML:** `extraction`, `llm`, `llm-router`, `speech`
- **UI/UX:** `design-tokens`, `dashboard-components`, `dashboard-shell`, `celebrations`, `gentle-notifications`, `quick-actions`, `time-references`, `accessibility`, `create-app`
- **Platform SDKs:** `swift-platform-sdk`, `kotlin-platform-sdk`, `react-native-platform-sdk`
_(All under the `@bytelyst/` scope — consumed via `file:` or `workspace:_` refs)\*
### 2.2 Services ### 2.2 Services
| Service | Purpose | | Service | Port | Purpose |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | -------------------- | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform-service` | Product-agnostic platform APIs: auth, flags, telemetry, diagnostics, jobs, analytics, A/B testing, changelog, webhooks, marketplace, predictive analytics, and more | | `platform-service` | 4003 | Product-agnostic platform APIs: auth, flags, telemetry, diagnostics, jobs, analytics, A/B testing, changelog, webhooks, marketplace, predictive analytics, orgs, SCIM, and more (63 modules) |
| `extraction-service` | LangExtract-based extraction tasks with Python sidecar | | `extraction-service` | 4005 | LangExtract-based extraction tasks with Python sidecar |
| `mcp-server` | MCP tool registry, tool execution, product/operator tools, and A2A orchestration pipelines | | `mcp-server` | 4007 | MCP tool registry, tool execution, product/operator tools, and A2A orchestration pipelines (14 tool namespaces) |
| `monitoring` | Loki/Grafana and health-check infrastructure | | `monitoring` | — | Loki/Grafana and health-check infrastructure |
### 2.3 Dashboards ### 2.3 Dashboards
@ -59,16 +68,19 @@
## 3. Product Repos and Shared Platform Consumption ## 3. Product Repos and Shared Platform Consumption
| Product | Shared Platform Dependencies | | Product | Port | Shared Platform Dependencies |
| ---------- | --------------------------------------------------------------------------------- | | ------------- | ---- | --------------------------------------------------------------------------------- |
| LysnrAI | shared packages, platform-service, extraction-service, dashboards integration | | LysnrAI | 4015 | shared packages, platform-service, extraction-service, dashboards integration |
| MindLyst | shared packages, extraction integration, design tokens, platform-service patterns | | MindLyst | 4014 | shared packages, extraction integration, design tokens, platform-service patterns |
| ChronoMind | shared packages, design token flow, platform-service patterns | | ChronoMind | 4011 | shared packages, design token flow, platform-service patterns |
| NomGap | React Native platform SDK, shared packages, platform-service patterns | | NomGap | 4013 | React Native platform SDK, shared packages, platform-service patterns |
| JarvisJr | shared SDKs, platform-service, marketplace patterns | | JarvisJr | 4012 | shared SDKs, platform-service, marketplace patterns |
| PeakPulse | Swift platform SDK, shared platform wrappers, design/system patterns | | PeakPulse | 4010 | Swift platform SDK, shared platform wrappers, design/system patterns |
| NoteLett | shared packages, platform-service, extraction-service, mobile/web client patterns | | NoteLett | 4016 | shared packages, platform-service, extraction-service, mobile/web client patterns |
| FlowMonk | shared packages, platform-service, offline queue, planning-platform patterns | | FlowMonk | 4017 | shared packages, platform-service, offline queue, planning-platform patterns |
| ActionTrail | 4018 | shared packages, platform-service, SSE/webhooks, SDK (@actiontrail/sdk) |
| SmartAuth | — | Extends platform-service auth module (no separate backend) |
| ByteLyst Auth | — | Consumes platform-service directly via Swift/Kotlin platform SDKs |
--- ---
@ -82,7 +94,23 @@
--- ---
## 5. Recommended Source-of-Truth Docs ## 5. Test Count Summary
| Component | Tests |
| -------------------- | ---------- |
| platform-service | ~1,050+ |
| extraction-service | ~47 |
| Product backends (9) | ~1,217 |
| ActionTrail SDK | 21 |
| ActionTrail E2E | 40 |
| Kotlin platform SDK | 57 |
| NomGap mobile tests | 505 |
| ChronoMind web tests | 373 |
| **Estimated total** | **3,500+** |
---
## 6. Recommended Source-of-Truth Docs
| Scope | Document | | Scope | Document |
| ------------------------------ | --------------------------------------------- | | ------------------------------ | --------------------------------------------- |
@ -91,11 +119,15 @@
| Agent implementation guidance | `AGENTS.md` | | Agent implementation guidance | `AGENTS.md` |
| High-level architecture | `docs/architecture/ECOSYSTEM_ARCHITECTURE.md` | | High-level architecture | `docs/architecture/ECOSYSTEM_ARCHITECTURE.md` |
| Canonical active repo list | `.windsurf/workflows/repos.txt` | | Canonical active repo list | `.windsurf/workflows/repos.txt` |
| MCP/A2A orchestration | `docs/MCP+A2A/README.md` |
| Azure resource inventory | `docs/devops/AZURE_RESOURCE_INVENTORY.md` |
--- ---
## 6. Notes ## 7. Notes
- This document reflects the currently active nine-repo workspace rather than the earlier three-repo migration model. - This document reflects the currently active 13-repo workspace (plus 1 prototype repo).
- Product-specific backends now live in their product repositories, while `learning_ai_common_plat` remains product-agnostic. - Product-specific backends now live in their product repositories, while `learning_ai_common_plat` remains product-agnostic.
- `mcp-server` and `ux-lab` are active capability surfaces and should be included in future inventory updates. - `mcp-server` and `ux-lab` are active capability surfaces.
- `learning_ai_local_memory_gpt` is a standalone prototype, not part of the ByteLyst ecosystem.
- `learning_ai_productivity_web` is an internal tools site, not a consumer of platform-service.

247
docs/learning_ai_common_plat_INVENTORY.md
View File

@ -2,7 +2,7 @@
> **Purpose:** Comprehensive reference for all reusable components, services, SDKs, and tools available to ByteLyst product teams. > **Purpose:** Comprehensive reference for all reusable components, services, SDKs, and tools available to ByteLyst product teams.
> **Repo:** `learning_ai_common_plat` > **Repo:** `learning_ai_common_plat`
> **Last Updated:** 2026-03-05 > **Last Updated:** 2026-03-20
--- ---
@ -10,12 +10,15 @@
| Category | Count | Notes | | Category | Count | Notes |
| --------------------- | ------- | -------------------------------------------------------------------- | | --------------------- | ------- | -------------------------------------------------------------------- |
| **Shared Packages** | 36 | `@bytelyst/*` — consumed via `file:` or `workspace:*` | | **Shared Packages** | 53 | `@bytelyst/*` — consumed via `file:` or `workspace:*` |
| **Platform Services** | 4 | `platform-service`, `extraction-service`, `mcp-server`, `monitoring` | | **Platform Services** | 4 | `platform-service`, `extraction-service`, `mcp-server`, `monitoring` |
| **Dashboards** | 3 | `admin-web`, `tracker-web`, `ux-lab` | | **Dashboards** | 3 | `admin-web`, `tracker-web`, `ux-lab` |
| **Platform SDKs** | 3 | Swift, Kotlin, React Native | | **Platform SDKs** | 3 | Swift, Kotlin, React Native |
| **Cosmos Containers** | ~50+ | Shared + product-specific | | **Platform Modules** | 63 | platform-service route modules |
| **Total Tests** | ~1,700+ | Service + package + SDK tests | | **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 (platform + products) |
--- ---
@ -34,24 +37,29 @@
### 2.2 Auth & Identity ### 2.2 Auth & Identity
| Package | Purpose | Exports | Consumers | | Package | Purpose | Exports | Consumers |
| ----------------------- | -------------------------- | -------------------------------------------------------------------------------- | ------------------------- | | ----------------------- | ---------------------------- | -------------------------------------------------------------------------------- | ------------------------- |
| `@bytelyst/auth` | JWT + password hashing | `createJwtUtils`, `hashPassword`, `verifyPassword`, `extractAuth`, `requireRole` | All services + dashboards | | `@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-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 | | `@bytelyst/react-auth` | React auth context factory | `createAuthContext()` — typed provider + hook | Next.js dashboards |
### 2.3 API & Clients ### 2.3 API & Clients
| Package | Purpose | Exports | Consumers | | Package | Purpose | Exports | Consumers |
| ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- | ---------------------------------- | | ------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------- | ----------------------------- |
| `@bytelyst/api-client` | Typed fetch wrapper | `createApiClient()` with auth injection | Web + RN | | `@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/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/broadcast-client` | Broadcast/survey client | Poll and broadcast APIs | iOS + Android |
| `@bytelyst/survey-client` | Survey response client | Submit survey responses | 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/telemetry-client` | Telemetry ingestion | `createTelemetryClient()` with batching | All platforms |
| `@bytelyst/feature-flag-client` | Feature flag polling | `createFeatureFlagClient()` | 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/kill-switch-client` | Kill switch check | `createKillSwitchClient()` (fail-open) | All platforms |
| `@bytelyst/offline-queue` | Persistent retry queue | Configurable storage adapter | Web + RN | | `@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/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 | | `@bytelyst/feedback-client` | In-app feedback | Submit feedback + attachments | iOS + Android |
### 2.4 Storage & Data ### 2.4 Storage & Data
@ -66,18 +74,23 @@
### 2.5 Backend Framework ### 2.5 Backend Framework
| Package | Purpose | Exports | Consumers | | Package | Purpose | Exports | Consumers |
| ------------------------ | ------------------------- | -------------------------------------------------- | -------------------- | | ---------------------------- | ------------------------- | -------------------------------------------------- | -------------------- |
| `@bytelyst/fastify-core` | Service bootstrap | `createServiceApp()`, `startService()`, Swagger UI | All Fastify services | | `@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/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/monitoring` | Health checks + telemetry | Health utilities, Loki/Grafana helpers | All services |
| `@bytelyst/push` | Push notification service | APNS, FCM integration | platform-service | | `@bytelyst/push` | Push notification service | APNS, FCM integration | platform-service |
### 2.6 AI/ML & Extraction ### 2.6 AI/ML & Extraction
| Package | Purpose | Exports | Consumers | | Package | Purpose | Exports | Consumers |
| ---------------------- | ---------------------- | ---------------------------------------- | ---------------- | | ---------------------- | ------------------------- | --------------------------------------------------- | ---------------- |
| `@bytelyst/extraction` | Text extraction client | `createExtractionClient()`, shared types | Web + dashboards | | `@bytelyst/extraction` | Text extraction client | `createExtractionClient()`, shared types | Web + dashboards |
| `@bytelyst/llm` | LLM utilities | Prompt templates, token counting | Services | | `@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 | | `@bytelyst/speech` | Speech SDK wrappers | Azure Speech integration | Desktop + Mobile |
### 2.7 Platform Experience & Sync ### 2.7 Platform Experience & Sync
@ -85,14 +98,21 @@
| Package | Purpose | Exports / Surface | Consumers | | Package | Purpose | Exports / Surface | Consumers |
| -------------------------------- | ----------------------------------- | ------------------------------------------- | ------------------ | | -------------------------------- | ----------------------------------- | ------------------------------------------- | ------------------ |
| `@bytelyst/dashboard-components` | Shared dashboard UI building blocks | Reusable admin/tracker UI primitives | Dashboards | | `@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/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 | | `@bytelyst/swift-diagnostics` | Swift diagnostics support | Crash/error helpers, diagnostics capture | Apple platforms |
### 2.8 Design System ### 2.8 Design System & UX
| Package | Purpose | Exports | Consumers | | Package | Purpose | Exports | Consumers |
| ------------------------- | --------------------- | --------------------------------- | ------------- | | -------------------------------- | ----------------------------- | ------------------------------------- | ------------- |
| `@bytelyst/design-tokens` | Cross-platform tokens | CSS, TS, Kotlin, Swift generation | All platforms | | `@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.9 React Native ### 2.9 React Native
@ -108,7 +128,7 @@
Consolidated from billing-service, growth-service, tracker-service. Consolidated from billing-service, growth-service, tracker-service.
**Status:** Active | **Tests:** ~1,050+ | **Modules:** 45 **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. **Route Note:** Route families below are shown in their deployed form. Most are registered under the `/api` prefix unless explicitly public.
@ -157,6 +177,26 @@ Consolidated from billing-service, growth-service, tracker-service.
| **impersonation** | User impersonation | `impersonation_sessions` | `/impersonation/*` | | **impersonation** | User impersonation | `impersonation_sessions` | `/impersonation/*` |
| **changelog** | Product changelogs | `changelogs` | `/api/changelog`, `/api/admin/changelog` | | **changelog** | Product changelogs | `changelogs` | `/api/changelog`, `/api/admin/changelog` |
| **ratelimit** | Rate limiting | `rate_limit_windows` | `/ratelimit/*` | | **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) ### 3.2 extraction-service (Port 4005)
@ -167,18 +207,26 @@ Consolidated from billing-service, growth-service, tracker-service.
| **extract** | Text extraction (LangExtract) | Python + TypeScript hybrid | | **extract** | Text extraction (LangExtract) | Python + TypeScript hybrid |
| **tasks** | Extraction task management | TypeScript | | **tasks** | Extraction task management | TypeScript |
### 3.3 mcp-server (Tooling + A2A orchestration) ### 3.3 mcp-server (Port 4007 — Tooling + A2A orchestration)
**Status:** Active | **Primary Role:** Tool registry + MCP tool execution + A2A orchestration layer **Status:** Active | **Primary Role:** Tool registry + MCP tool execution + A2A orchestration layer | **Namespaces:** 14
| Namespace / Area | Purpose | Surface | | Namespace / Area | Purpose | Surface |
| ---------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------- | | ---------------- | ----------------------------------------------------------------------------------------- | ------------------------------- |
| **tools** | Tool registry, schema exposure, execution routing | `/api/tools`, `/api/tools/call` | | **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 | | **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 | | **extraction** | MCP wrappers for extraction workflows | MCP tools |
| **a2a** | Cross-product agent-to-agent pipelines and orchestration flows | Pipeline 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 | | **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 | | **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 ### 3.4 monitoring
@ -232,9 +280,15 @@ Consolidated from billing-service, growth-service, tracker-service.
**Stack:** Experimental/internal dashboard workbench for operations UI kits, scoped prototypes, and MCP-driven UX workflows. **Stack:** Experimental/internal dashboard workbench for operations UI kits, scoped prototypes, and MCP-driven UX workflows.
| Area | Description | | 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-ops-ui-kit/` | Internal UI kit and scoping docs for ops/dashboard work |
| Prototypes | Workspace for UX exploration, MCP-assisted workflows, and internal experimentation | | `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 |
--- ---
@ -319,6 +373,7 @@ Workflow scripts for AI agents and developers:
| Workflow | Purpose | | Workflow | Purpose |
| -------------------------- | -------------------------------------- | | -------------------------- | -------------------------------------- |
| `README.md` | Skills directory overview |
| `architecture-patterns.md` | Common architectural patterns | | `architecture-patterns.md` | Common architectural patterns |
| `backup-main-branch.md` | Smart backup with duplicate detection | | `backup-main-branch.md` | Smart backup with duplicate detection |
| `debug-service.md` | Debug failing services | | `debug-service.md` | Debug failing services |
@ -343,20 +398,25 @@ Workflow scripts for AI agents and developers:
## 7. Scripts (`scripts/`) ## 7. Scripts (`scripts/`)
| Script | Purpose | | Script | Purpose |
| ----------------------------- | ------------------------------------- | | ----------------------------- | -------------------------------------------- |
| `backup-main.sh` | Backup main branches across repos | | `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 | | `cosmos-telemetry-indexes.sh` | Create Cosmos indexes for telemetry |
| `docker-prep.sh` | Prepare for Docker builds | | `docker-prep.sh` | Prepare for Docker builds |
| `export-lysnr-kv.sh` | Export LysnrAI Key Vault secrets | | `export-lysnr-kv.sh` | Export LysnrAI Key Vault secrets |
| `prep-consumer.sh` | Prepare consumer builds | | `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-deploy.sh` | Deploy to Railway |
| `railway-sync-env.sh` | Sync env vars to Railway |
| `secret-scan-repo.sh` | Scan repo for secrets | | `secret-scan-repo.sh` | Scan repo for secrets |
| `secret-scan-staged.sh` | Scan staged files | | `secret-scan-staged.sh` | Scan staged files |
| `seed-keyvault.sh` | Seed Key Vault with required secrets | | `seed-keyvault.sh` | Seed Key Vault with required secrets |
| `seed-lysnr-kv.sh` | Seed LysnrAI Key Vault | | `seed-lysnr-kv.sh` | Seed LysnrAI Key Vault |
| `setup-husky.sh` | Setup Git hooks | | `setup-husky.sh` | Setup Git hooks |
| `switch-network.sh` | Switch between corporate/home network | | `switch-network.sh` | Switch between corporate/home network |
| `sync-workflows.md` | Sync workflows across repos | | `sync-workflows.sh` | Sync workflows across repos |
| `update-agent-docs.sh` | Regenerate AGENTS.md, CLAUDE.md across repos |
--- ---
@ -364,14 +424,15 @@ Workflow scripts for AI agents and developers:
Each product has a `product.json` manifest: Each product has a `product.json` manifest:
| Product | File | Backend Port | | Product | File | Backend Port | Repo |
| ---------- | ------------------------- | ------------ | | ---------- | ------------------------- | ------------ | ----------------------------------- |
| LysnrAI | `lysnrai/product.json` | 4015 | | LysnrAI | `lysnrai/product.json` | 4015 | `learning_voice_ai_agent` |
| MindLyst | `mindlyst/product.json` | 4014 | | MindLyst | `mindlyst/product.json` | 4014 | `learning_multimodal_memory_agents` |
| ChronoMind | `chronomind/product.json` | 4011 | | ChronoMind | `chronomind/product.json` | 4011 | `learning_ai_clock` |
| JarvisJr | `jarvisjr/product.json` | 4012 | | JarvisJr | `jarvisjr/product.json` | 4012 | `learning_ai_jarvis_jr` |
| NomGap | `nomgap/product.json` | 4013 | | NomGap | `nomgap/product.json` | 4013 | `learning_ai_fastgap` |
| PeakPulse | `peakpulse/product.json` | 4010 | | PeakPulse | `peakpulse/product.json` | 4010 | `learning_ai_peakpulse` |
| NoteLett | `notelett/product.json` | 4016 | `learning_ai_notes` |
--- ---
@ -386,7 +447,9 @@ Each product has a `product.json` manifest:
| `mobile_ANDROID_PLATFORM_SDK.md` | Android SDK design | | `mobile_ANDROID_PLATFORM_SDK.md` | Android SDK design |
| `mobile_IOS_PLATFORM_SDK.md` | iOS SDK design | | `mobile_IOS_PLATFORM_SDK.md` | iOS SDK design |
| `mobile_REACT_NATIVE_PLATFORM_SDK.md` | React Native 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_BACKEND_MIGRATION.md` | Backend consolidation |
| `platform_BROADCAST_SURVEY_ROADMAP.md` | Broadcast + survey system |
| `platform_COMMON_EXTRACTION_ROADMAP.md` | Shared extraction | | `platform_COMMON_EXTRACTION_ROADMAP.md` | Shared extraction |
| `platform_COMPONENTS_ROADMAP.md` | Platform components (23 of 25 built) | | `platform_COMPONENTS_ROADMAP.md` | Platform components (23 of 25 built) |
| `platform_SERVICE_CONSOLIDATION_ROADMAP.md` | Service merger (4001→4003) | | `platform_SERVICE_CONSOLIDATION_ROADMAP.md` | Service merger (4001→4003) |
@ -398,18 +461,80 @@ Each product has a `product.json` manifest:
## 10. Active/Planned Roadmaps (`docs/roadmaps/`) ## 10. Active/Planned Roadmaps (`docs/roadmaps/`)
### 10.1 Active Roadmaps
| Roadmap | Status | | Roadmap | Status |
| -------------------------------------------- | ----------- | | -------------------------------------------- | ----------- |
| `AI_DIAGNOSTIC_ASSISTANT_ROADMAP.md` | In Progress | | `AI_DIAGNOSTIC_ASSISTANT_ROADMAP.md` | In Progress |
| `INTELLIGENT_AB_TESTING_ROADMAP.md` | Active | | `INTELLIGENT_AB_TESTING_ROADMAP.md` | Active |
| `P3_PLATFORM_DEEPENING_ROADMAP.md` | Active |
| `PREDICTIVE_CHURN_HEALTH_SCORING_ROADMAP.md` | Active | | `PREDICTIVE_CHURN_HEALTH_SCORING_ROADMAP.md` | Active |
| `WORKSPACE_REVIEW_2026_03_03.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. How to Consume ## 11. Documentation Directory (`docs/`)
### 11.1 TypeScript Packages (Services/Dashboards) | 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 ```json
// package.json // package.json
@ -429,7 +554,7 @@ import { createJwtUtils } from '@bytelyst/auth';
import { loadProductIdentity } from '@bytelyst/config'; import { loadProductIdentity } from '@bytelyst/config';
``` ```
### 11.2 Swift SDK (iOS) ### 13.2 Swift SDK (iOS)
```swift ```swift
// Package.swift // Package.swift
@ -442,7 +567,7 @@ import ByteLystPlatformSDK
let config = BLPlatformConfig(productId: "myproduct", baseURL: "...") let config = BLPlatformConfig(productId: "myproduct", baseURL: "...")
``` ```
### 11.3 Kotlin SDK (Android) ### 13.3 Kotlin SDK (Android)
```kotlin ```kotlin
// settings.gradle.kts // settings.gradle.kts
@ -456,7 +581,7 @@ import com.bytelyst.platform.BLPlatformConfig
val config = BLPlatformConfig(productId = "myproduct", baseURL = "...") val config = BLPlatformConfig(productId = "myproduct", baseURL = "...")
``` ```
### 11.4 React Native SDK ### 13.4 React Native SDK
```json ```json
// package.json // package.json
@ -469,7 +594,7 @@ val config = BLPlatformConfig(productId = "myproduct", baseURL = "...")
--- ---
## 12. Build Verification Commands ## 14. Build Verification Commands
```bash ```bash
# Full platform build # Full platform build
@ -497,51 +622,55 @@ cd dashboards/tracker-web && npm run build
--- ---
## 13. Architecture Diagram ## 15. Architecture Diagram
``` ```
┌─────────────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────────────────────────────┐
│ PRODUCT APPS │ │ PRODUCT APPS (9) │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │LysnrAI │ │MindLyst │ │ChronoM. │ │JarvisJr │ │NomGap │ │ │ │LysnrAI │ │MindLyst │ │ChronoM. │ │JarvisJr │ │NomGap │ │
│ │PeakPulse│ │ │ │ │ │ │ │ ││ │ │ :4015 │ │ :4014 │ │ :4011 │ │ :4012 │ │ :4013 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │ │ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │ │ │ │ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ ┌────┴────┐ │
│ └───────────┴───────────┴───────────┴───────────┘ │ │ │PeakPulse│ │NoteLett │ │FlowMonk │ │Action │ │
│ │ :4010 │ │ :4016 │ │ :4017 │ │Trail │ │
│ │ │ │ │ │ │ │ :4018 │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ └────┬────┘ │
│ └───────────┴───────────┴───────────┘ │
│ │ │ │ │ │
│ ┌──────────┴──────────┐ │ │ ┌──────────┴──────────┐ │
│ │ Platform SDKs │ │ │ │ Platform SDKs (3) │ │
│ │ (Swift/Kotlin/RN) │ │ │ │ Swift/Kotlin/RN │ │
│ └──────────┬──────────┘ │ │ └──────────┬──────────┘ │
└─────────────────────────┼───────────────────────────────────┘ └─────────────────────────┼────────────────────────────────────────────────┘
│ │
┌─────────────────────────┼───────────────────────────────────┐ ┌─────────────────────────┼────────────────────────────────────────────────┐
│ ┌──────────┴──────────┐ │ │ ┌──────────┴──────────┐ │
│ │ Shared Packages │ │ │ │ Shared Packages (53)│ │
│ │ (@bytelyst/*) │ │ │ │ (@bytelyst/*) │ │
│ └──────────┬──────────┘ │ │ └──────────┬──────────┘ │
│ │ │ │ │ │
│ ┌──────────────────────┼────────────────────────────────┐ │ │ ┌──────────────────────┼──────────────────────────────────────────┐ │
│ │ platform-service (4003) │ │ │ │ platform-service (4003) — 63 modules │ │
│ │ auth │ billing │ flags │ telemetry │ blob │ etc. │ │ │ │ auth │ flags │ telemetry │ blob │ orgs │ billing │ etc. │ │
│ └──────────────────────┬────────────────────────────────┘ │ │ └──────────────────────┬──────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ┌──────────────────────┼────────────────────────────────┐ │ │ ┌──────────────────────┼──────────────────────────────────────────┐ │
│ │ extraction-service (4005) │ │ │ │ extraction-service (4005) │ mcp-server (4007) │ │
│ │ Text extraction (LangExtract) │ │ │ │ Text extraction (LangExtract) │ MCP tools + A2A (14 ns) │ │
│ └──────────────────────┬────────────────────────────────┘ │ │ └──────────────────────┬──────────────────────────────────────────┘ │
│ │ │ │ │ │
│ ┌──────────┴──────────┐ │ │ ┌──────────┴──────────┐ │
│ │ Azure Cosmos DB │ │ │ │ Azure Cosmos DB │ │
│ │ Azure Blob Storage │ │ │ │ Azure Blob Storage │ │
│ │ Azure Key Vault │ │ │ │ Azure Key Vault │ │
│ └───────────────────────┘ │ │ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────┘ └───────────────────────────────────────────────────────────────────────────┘
``` ```
--- ---
## 14. Contact & Contribution ## 16. Contact & Contribution
- **Primary Repo:** `learning_ai_common_plat` - **Primary Repo:** `learning_ai_common_plat`
- **Package Scope:** `@bytelyst/*` - **Package Scope:** `@bytelyst/*`

22
packages/diagnostics-client/src/index.ts
View File

@ -35,25 +35,15 @@
* ``` * ```
*/ */
export { export { DiagnosticsClient, type DiagnosticsClientOptions } from './client.js';
DiagnosticsClient,
type DiagnosticsClientOptions,
} from './client.js';
export { export { createWebDiagnostics, type WebDiagnosticsConfig } from './web.js';
BreadcrumbTrail,
type BreadcrumbTrailOptions,
} from './breadcrumbs.js';
export { export { BreadcrumbTrail, type BreadcrumbTrailOptions } from './breadcrumbs.js';
NetworkInterceptor,
type NetworkInterceptorOptions,
} from './network.js';
export { export { NetworkInterceptor, type NetworkInterceptorOptions } from './network.js';
collectDeviceState,
subscribeToConnectivity, export { collectDeviceState, subscribeToConnectivity } from './device.js';
} from './device.js';
export type { export type {
LogLevel, LogLevel,

111
packages/diagnostics-client/src/web.ts Normal file
View File

@ -0,0 +1,111 @@
/**
* Convenience factory for web dashboard diagnostics.
*
* Eliminates ~40 lines of boilerplate per web app by wrapping
* DiagnosticsClient.getInstance() with sensible web defaults.
*
* @example
* ```ts
* import { createWebDiagnostics } from '@bytelyst/diagnostics-client';
*
* const { init, stop } = createWebDiagnostics({
* productId: 'nomgap',
* channel: 'nomgap_web',
* serverUrl: 'http://localhost:4003',
* getAuthToken: () => localStorage.getItem('nomgap_access_token') ?? '',
* });
* export { init as initDiagnostics, stop as stopDiagnostics };
* ```
*/
import { DiagnosticsClient } from './client.js';
export interface WebDiagnosticsConfig {
/** Product identifier (e.g. 'nomgap', 'chronomind'). */
productId: string;
/** Channel identifier (e.g. 'nomgap_web', 'pwa'). */
channel: string;
/** Platform-service origin URL (no trailing /api). */
serverUrl: string;
/** Function that returns the current auth token. */
getAuthToken: () => string;
/** App version string. Default: '0.1.0'. */
appVersion?: string;
/** Build number. Default: '1'. */
buildNumber?: string;
/** Release channel. Default: 'dev'. */
releaseChannel?: string;
/** OS family. Default: 'unknown'. */
osFamily?: string;
/** Poll interval in ms. Default: 30000. */
pollIntervalMs?: number;
/** Capture console logs. Default: false. */
captureConsole?: boolean;
/** Capture JS errors. Default: true. */
captureErrors?: boolean;
/** Capture network requests. Default: false. */
captureNetwork?: boolean;
}
export interface WebDiagnostics {
/** Initialize diagnostics. Safe to call on server (no-ops). Idempotent. */
init(): void;
/** Stop diagnostics polling. */
stop(): void;
}
function getOrCreateInstallId(productId: string): string {
const key = `${productId}_diag_install_id`;
let id = localStorage.getItem(key);
if (!id) {
id =
typeof crypto?.randomUUID === 'function'
? crypto.randomUUID()
: Math.random().toString(36).slice(2) + Date.now().toString(36);
localStorage.setItem(key, id);
}
return id;
}
export function createWebDiagnostics(config: WebDiagnosticsConfig): WebDiagnostics {
let started = false;
function init(): void {
if (typeof window === 'undefined') return;
if (started) return;
DiagnosticsClient.getInstance({
productId: config.productId,
anonymousInstallId: getOrCreateInstallId(config.productId),
platform: 'web',
channel: config.channel,
osFamily: config.osFamily ?? 'unknown',
appVersion: config.appVersion ?? '0.1.0',
buildNumber: config.buildNumber ?? '1',
releaseChannel: config.releaseChannel ?? 'dev',
serverUrl: config.serverUrl,
getAuthToken: config.getAuthToken,
pollIntervalMs: config.pollIntervalMs ?? 30_000,
captureConsole: config.captureConsole ?? false,
captureErrors: config.captureErrors ?? true,
captureNetwork: config.captureNetwork ?? false,
});
DiagnosticsClient.getInstance()
.start()
.catch(() => {
// Diagnostics is best-effort
});
started = true;
}
function stop(): void {
try {
DiagnosticsClient.getInstance().stop();
} catch {
// not initialized
}
}
return { init, stop };
}

1
packages/telemetry-client/src/index.ts
View File

@ -1,4 +1,5 @@
export { createTelemetryClient } from './client.js'; export { createTelemetryClient } from './client.js';
export { createWebTelemetry, type WebTelemetryConfig } from './web.js';
export type { export type {
TelemetryClient, TelemetryClient,
TelemetryClientConfig, TelemetryClientConfig,

81
packages/telemetry-client/src/web.ts Normal file
View File

@ -0,0 +1,81 @@
/**
* Convenience factory for web dashboard telemetry.
*
* Eliminates ~30 lines of boilerplate per web app by wrapping
* createTelemetryClient() with sensible web defaults.
*
* @example
* ```ts
* import { createWebTelemetry } from '@bytelyst/telemetry-client';
*
* const { client, init, trackPageView } = createWebTelemetry({
* productId: 'nomgap',
* channel: 'nomgap_web',
* });
* export { client as telemetryClient, init as initTelemetry, trackPageView };
* ```
*/
import { createTelemetryClient } from './client.js';
import type { TelemetryClient } from './types.js';
export interface WebTelemetryConfig {
/** Product identifier (e.g. 'nomgap', 'chronomind'). */
productId: string;
/** Channel identifier (e.g. 'nomgap_web', 'pwa'). */
channel: string;
/** Platform-service base URL. Default: 'http://localhost:4003/api'. */
baseUrl?: string;
/** Telemetry ingest endpoint path. Default: '/telemetry/events'. */
endpoint?: string;
/** Transport: 'beacon' or 'fetch'. Default: 'fetch'. */
transport?: 'beacon' | 'fetch';
/** App version string. Default: '0.1.0'. */
appVersion?: string;
/** Build number. Default: '1'. */
buildNumber?: string;
/** Release channel. Default: 'dev'. */
releaseChannel?: string;
/** OS family. Default: 'other'. */
osFamily?: string;
}
export interface WebTelemetry {
/** The underlying telemetry client instance. */
client: TelemetryClient;
/** Initialize telemetry and track app_initialized event. Idempotent. */
init(): TelemetryClient;
/** Track a page view event. */
trackPageView(page: string): void;
}
export function createWebTelemetry(config: WebTelemetryConfig): WebTelemetry {
let initialized = false;
const client = createTelemetryClient({
productId: config.productId,
baseUrl: config.baseUrl ?? 'http://localhost:4003/api',
endpoint: config.endpoint ?? '/telemetry/events',
platform: 'web',
channel: config.channel,
transport: config.transport ?? 'fetch',
appVersion: config.appVersion ?? '0.1.0',
buildNumber: config.buildNumber ?? '1',
releaseChannel: config.releaseChannel ?? 'dev',
osFamily: config.osFamily ?? 'other',
});
function init(): TelemetryClient {
if (initialized) return client;
client.init();
client.trackEvent('info', 'app_shell', 'web_app_initialized');
initialized = true;
return client;
}
function trackPageView(page: string): void {
client.trackEvent('info', 'navigation', 'page_view', { feature: page });
}
return { client, init, trackPageView };
}