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

docs(inventory): refresh platform and workspace capability maps

Browse Source
This commit is contained in:
saravanakumardb1 2026-03-05 22:59:45 -08:00
parent d365bc59d6
commit 8f63713c52
4 changed files with 324 additions and 182 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
README.md
View File

@ -21,7 +21,7 @@ pnpm build
# Quick quality check (5 min) - run before pushing! # Quick quality check (5 min) - run before pushing!
./quick-check.sh ./quick-check.sh
# Run all tests (165 total across packages + services) # Run all tests
pnpm test pnpm test
# Type-check all packages # Type-check all packages
@ -31,80 +31,75 @@ pnpm typecheck
pnpm --filter @lysnrai/platform-service dev pnpm --filter @lysnrai/platform-service dev
``` ```
## Current Capability Surface
- **Shared packages** — 36 `@bytelyst/*` packages covering auth, config, API clients, storage, sync, telemetry, diagnostics, design tokens, SDK support, and testing.
- **Services** — `platform-service`, `extraction-service`, `mcp-server`, and `monitoring`.
- **Dashboards** — `admin-web`, `tracker-web`, and `ux-lab`.
- **MCP/A2A** — `services/mcp-server/` exposes tool routing, platform operator tools, extraction helpers, dev tools, product namespaces, and A2A orchestration pipelines.
## Repository Structure ## Repository Structure
``` ```
learning_ai_common_plat/ learning_ai_common_plat/
├── packages/ # Shared libraries (@bytelyst/*) ├── packages/ # 36 shared libraries (@bytelyst/*)
│ ├── errors/ # Typed HTTP service errors (400–429) │ ├── api-client/
│ ├── cosmos/ # Azure Cosmos DB client + container registry │ ├── auth/
│ ├── config/ # Zod env loader + product identity │ ├── auth-client/
│ ├── auth/ # JWT, middleware, password hashing │ ├── blob/ + blob-client/
│ ├── api-client/ # Configurable fetch wrapper │ ├── broadcast-client/ + survey-client/
│ ├── react-auth/ # React auth context factory │ ├── config/ + cosmos/
│ └── design-tokens/ # Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift) │ ├── dashboard-components/
├── dashboards/ # Product-agnostic web dashboards (Next.js) │ ├── design-tokens/
│ ├── diagnostics-client/ + swift-diagnostics/
│ ├── events/ + fastify-core/
│ ├── extraction/ + llm/ + speech/
│ ├── feature-flag-client/ + feedback-client/ + kill-switch-client/
│ ├── kotlin-platform-sdk/ + swift-platform-sdk/ + react-native-platform-sdk/
│ ├── logger/ + monitoring/ + testing/
│ ├── offline-queue/ + platform-client/ + sync/ + telemetry-client/
│ └── datastore/ + storage/ + push/
├── dashboards/ # Product-agnostic and internal web workspaces
│ ├── admin-web/ # Platform admin console (port 3001) │ ├── admin-web/ # Platform admin console (port 3001)
│ └── tracker-web/ # Issue tracker + public roadmap (port 3003) │ ├── tracker-web/ # Issue tracker + public roadmap (port 3003)
├── services/ # Product-agnostic microservices │ └── ux-lab/ # Internal UX lab / MCP-assisted ops prototypes
│ ├── platform-service/ # Consolidated: auth, audit, flags, billing, growth, tracker (port 4003) ├── services/ # Platform services + tooling servers
│ ├── platform-service/ # Product-agnostic platform API (port 4003)
│ ├── extraction-service/ # LangExtract text extraction + Python sidecar (port 4005) │ ├── extraction-service/ # LangExtract text extraction + Python sidecar (port 4005)
│ ├── mcp-server/ # MCP tool server + A2A orchestration
│ └── monitoring/ # Loki + Grafana config, health-check │ └── monitoring/ # Loki + Grafana config, health-check
└── docs/ # Architecture docs, roadmap, analysis └── docs/ # Architecture docs, roadmap, analysis
``` ```
## Shared Libraries ## Package Families
| Package | Description | Peer Dependencies | | Family | Representative Packages | Purpose |
| ------------------------- | --------------------------------------------------------- | ---------------------- | | ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- |
| `@bytelyst/errors` | Typed HTTP service errors (400–429) | — | | Core platform | `@bytelyst/config`, `@bytelyst/cosmos`, `@bytelyst/errors`, `@bytelyst/logger`, `@bytelyst/testing` | Shared infrastructure for all services and dashboards |
| `@bytelyst/logger` | Structured logger factory for services/dashboards | — | | Auth & app clients | `@bytelyst/auth`, `@bytelyst/auth-client`, `@bytelyst/api-client`, `@bytelyst/platform-client`, `@bytelyst/react-auth` | Identity, auth flows, typed service clients |
| `@bytelyst/cosmos` | Azure Cosmos DB client singleton + container registry | `@azure/cosmos` | | Diagnostics & telemetry | `@bytelyst/diagnostics-client`, `@bytelyst/telemetry-client`, `@bytelyst/swift-diagnostics` | Client diagnostics, event batching, crash/error capture |
| `@bytelyst/blob` | Azure Blob Storage helpers + SAS URL generation | `@azure/storage-blob` | | Storage & sync | `@bytelyst/blob`, `@bytelyst/blob-client`, `@bytelyst/datastore`, `@bytelyst/storage`, `@bytelyst/sync`, `@bytelyst/offline-queue` | Blob, local persistence, sync orchestration |
| `@bytelyst/config` | Zod-based env config loader + product identity | `zod` | | Product experience | `@bytelyst/feature-flag-client`, `@bytelyst/feedback-client`, `@bytelyst/broadcast-client`, `@bytelyst/survey-client`, `@bytelyst/kill-switch-client` | Runtime platform features for product apps |
| `@bytelyst/auth` | JWT utilities, auth middleware, password hashing | `jose`, `bcryptjs` | | AI & extraction | `@bytelyst/extraction`, `@bytelyst/llm`, `@bytelyst/speech` | Extraction tasks, LLM utilities, speech integration |
| `@bytelyst/fastify-core` | Fastify service bootstrap (request-id, /health, errors) | `fastify` | | UI & design | `@bytelyst/design-tokens`, `@bytelyst/dashboard-components` | Shared tokens and dashboard UI building blocks |
| `@bytelyst/api-client` | Configurable fetch wrapper with auth token injection | — | | Native SDKs | `@bytelyst/swift-platform-sdk`, `@bytelyst/kotlin-platform-sdk`, `@bytelyst/react-native-platform-sdk` | Cross-platform mobile/native platform access |
| `@bytelyst/react-auth` | React auth context factory (typed provider + hook) | `react` |
| `@bytelyst/design-tokens` | Cross-platform design tokens (JSON → CSS/TS/Kotlin/Swift) | — |
| `@bytelyst/extraction` | Extraction service client + shared types | `@bytelyst/api-client` |
| `@bytelyst/testing` | Shared test helpers (Fastify inject, schema asserts) | `vitest` |
| `@bytelyst/monitoring` | Health-check aggregation utilities | — |
## Shared Services ## Services and Dashboards
| Service | Port | Description | Tests | | Surface | Port | Description |
| -------------------- | ---- | ------------------------------------------------------------------------------ | ------ | | -------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform-service` | 4003 | Consolidated: auth, audit, flags, billing, growth, tracker, telemetry, etc. | 1,029 | | `platform-service` | 4003 | Product-agnostic Fastify platform API: auth, flags, telemetry, diagnostics, jobs, analytics, A/B testing, changelog, webhooks, marketplace, predictive analytics, and more |
| `extraction-service` | 4005 | LangExtract text extraction + Python sidecar | 46 | | `extraction-service` | 4005 | LangExtract-based extraction service with task library and Python sidecar |
| `monitoring` | — | Loki + Grafana dashboards, health-check script | — | | `mcp-server` | configurable | MCP server exposing tool execution, platform tools, dev tools, extraction helpers, and A2A orchestration pipelines |
| `monitoring` | — | Loki, Grafana, and health-check tooling |
| `admin-web` | 3001 | Platform admin console |
| `tracker-web` | 3003 | Tracker / public roadmap dashboard |
| `ux-lab` | internal | Internal UX lab and ops prototyping workspace |
> Note: billing-service (4002), growth-service (4001), and tracker-service (4004) were consolidated into platform-service (Feb 2026). > Note: billing-service (4002), growth-service (4001), and tracker-service (4004) were consolidated into platform-service (Feb 2026).
All services are **product-agnostic** — every Cosmos document includes a `productId` field, so a single deployment serves LysnrAI, MindLyst, or any future product. All services are **product-agnostic** — every Cosmos document includes a `productId` field, so a single deployment serves LysnrAI, MindLyst, or any future product.
## Quick Start
```bash
# Install dependencies
pnpm install
# Build all packages + services
pnpm build
# Quick quality check (5 min) - run before pushing!
./quick-check.sh
# Run all tests (165 total across packages + services)
pnpm test
# Type-check all packages
pnpm typecheck
# Run a specific service in dev mode
pnpm --filter @lysnrai/platform-service dev
```
## Consuming Libraries from Product Repos ## Consuming Libraries from Product Repos
During development, use `file:` references in consumer `package.json`: During development, use `file:` references in consumer `package.json`:
@ -141,7 +136,7 @@ docker build <target-dir>
Each consumer repo has a convenience wrapper: `scripts/docker-prep.sh` (or `scripts/docker-prep-dashboards.sh` in LysnrAI). Each consumer repo has a convenience wrapper: `scripts/docker-prep.sh` (or `scripts/docker-prep-dashboards.sh` in LysnrAI).
| Consumer Repo | Wrapper Script | Targets | | Consumer Repo | Wrapper Script | Targets |
|---------------|---------------|---------| | ----------------------------------- | ----------------------------------- | --------------------- |
| `learning_voice_ai_agent` | `scripts/docker-prep-dashboards.sh` | `user-dashboard-web` | | `learning_voice_ai_agent` | `scripts/docker-prep-dashboards.sh` | `user-dashboard-web` |
| `learning_ai_clock` | `scripts/docker-prep.sh` | `web` | | `learning_ai_clock` | `scripts/docker-prep.sh` | `web` |
| `learning_ai_fastgap` | `scripts/docker-prep.sh` | root `package.json` | | `learning_ai_fastgap` | `scripts/docker-prep.sh` | root `package.json` |

97
docs/WORKSPACE_INVENTORY.md Normal file
View File

@ -0,0 +1,97 @@
# ByteLyst Workspace Inventory
> **Purpose:** Workspace-level inventory for the active multi-repo ByteLyst development environment.
> **Workspace Root:** `~/code/mygh/`
> **Canonical Repo List:** `.windsurf/workflows/repos.txt`
> **Last Updated:** 2026-03-05
---
## 1. Active Workspace Repositories
| 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_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_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_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 |
---
## 2. Shared Platform Repo Role
`learning_ai_common_plat` is the shared infrastructure layer for the whole workspace.
### 2.1 Shared Packages
- `@bytelyst/config`, `@bytelyst/cosmos`, `@bytelyst/errors`, `@bytelyst/logger`, `@bytelyst/testing`
- `@bytelyst/auth`, `@bytelyst/auth-client`, `@bytelyst/api-client`, `@bytelyst/platform-client`, `@bytelyst/react-auth`
- `@bytelyst/blob`, `@bytelyst/blob-client`, `@bytelyst/datastore`, `@bytelyst/storage`, `@bytelyst/sync`, `@bytelyst/offline-queue`
- `@bytelyst/telemetry-client`, `@bytelyst/diagnostics-client`, `@bytelyst/swift-diagnostics`
- `@bytelyst/feature-flag-client`, `@bytelyst/feedback-client`, `@bytelyst/broadcast-client`, `@bytelyst/survey-client`, `@bytelyst/kill-switch-client`
- `@bytelyst/design-tokens`, `@bytelyst/dashboard-components`
- `@bytelyst/extraction`, `@bytelyst/llm`, `@bytelyst/speech`
- `@bytelyst/swift-platform-sdk`, `@bytelyst/kotlin-platform-sdk`, `@bytelyst/react-native-platform-sdk`
### 2.2 Services
| Service | Purpose |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `platform-service` | Product-agnostic platform APIs: auth, flags, telemetry, diagnostics, jobs, analytics, A/B testing, changelog, webhooks, marketplace, predictive analytics, and more |
| `extraction-service` | LangExtract-based extraction tasks with Python sidecar |
| `mcp-server` | MCP tool registry, tool execution, product/operator tools, and A2A orchestration pipelines |
| `monitoring` | Loki/Grafana and health-check infrastructure |
### 2.3 Dashboards
| Dashboard | Purpose |
| ------------- | ----------------------------------------- |
| `admin-web` | Platform admin console |
| `tracker-web` | Tracker and public roadmap dashboard |
| `ux-lab` | Internal UX and ops prototyping workspace |
---
## 3. Product Repos and Shared Platform Consumption
| Product | Shared Platform Dependencies |
| ---------- | --------------------------------------------------------------------------------- |
| LysnrAI | shared packages, platform-service, extraction-service, dashboards integration |
| MindLyst | shared packages, extraction integration, design tokens, platform-service patterns |
| ChronoMind | shared packages, design token flow, platform-service patterns |
| NomGap | React Native platform SDK, shared packages, platform-service patterns |
| JarvisJr | shared SDKs, platform-service, marketplace patterns |
| PeakPulse | Swift platform SDK, shared platform wrappers, design/system patterns |
---
## 4. Workspace Operating Model
- Common platform changes land first when shared packages or shared services change.
- Product repos consume `workspace:*` or `file:` references during local development.
- Repo workflows use `.windsurf/workflows/repos.txt` as the source of truth.
- Backup, sync, and workspace commit workflows operate across all active repos.
- MCP/A2A capabilities in `learning_ai_common_plat/services/mcp-server/` provide cross-product orchestration and operator tooling.
---
## 5. Recommended Source-of-Truth Docs
| Scope | Document |
| ------------------------------ | --------------------------------------------- |
| Common platform repo inventory | `docs/learning_ai_common_plat_INVENTORY.md` |
| Whole active workspace | `docs/WORKSPACE_INVENTORY.md` |
| Agent implementation guidance | `AGENTS.md` |
| High-level architecture | `docs/architecture/ECOSYSTEM_ARCHITECTURE.md` |
| Canonical active repo list | `.windsurf/workflows/repos.txt` |
---
## 6. Notes
- This document reflects the currently active seven-repo workspace rather than the earlier three-repo migration model.
- 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.

134
docs/architecture/ECOSYSTEM_ARCHITECTURE.md
View File

@ -2,14 +2,14 @@
> **Companion diagram:** `ecosystem-after-refactor.drawio` (open in draw.io or VS Code draw.io extension) > **Companion diagram:** `ecosystem-after-refactor.drawio` (open in draw.io or VS Code draw.io extension)
> >
> **Date:** 2026-02-12 · **Author:** Cascade > **Date:** 2026-03-05 · **Author:** Cascade
--- ---
## Table of Contents ## Table of Contents
1. [Ecosystem Overview](#1-ecosystem-overview) 1. [Ecosystem Overview](#1-ecosystem-overview)
2. [Three-Repo Structure](#2-three-repo-structure) 2. [Workspace Structure](#2-workspace-structure)
3. [Common Platform Packages — Detailed](#3-common-platform-packages--detailed) 3. [Common Platform Packages — Detailed](#3-common-platform-packages--detailed)
4. [Component & Service Inventory](#4-component--service-inventory) 4. [Component & Service Inventory](#4-component--service-inventory)
5. [Dependency Graph](#5-dependency-graph) 5. [Dependency Graph](#5-dependency-graph)
@ -25,82 +25,92 @@
## 1. Ecosystem Overview ## 1. Ecosystem Overview
The ByteLyst ecosystem consists of **two product repos** and **one shared infrastructure repo**: The active ByteLyst workspace consists of **seven product/shared repositories** coordinated side-by-side under `~/code/mygh/`, with `learning_ai_common_plat` serving as the shared infrastructure and platform capability layer:
``` ```
┌─────────────────────────────────────────────────────────────────────────┐ ┌──────────────────────────────────────────────────────────────────────────────┐
│ CLIENT APPLICATIONS │ │ ACTIVE WORKSPACE REPOS │
│ LysnrAI Desktop · iOS · Android · Admin · User Portal · Tracker │ │ learning_ai_common_plat → shared packages, services, dashboards, MCP │
│ MindLyst iOS · Android · Web │ │ learning_voice_ai_agent → LysnrAI │
└───────────────────────────────┬──────────────────────────────────────────┘ │ learning_multimodal_memory_agents → MindLyst │
│ learning_ai_clock → ChronoMind │
│ learning_ai_fastgap → NomGap │
│ learning_ai_jarvis_jr → JarvisJr │
│ learning_ai_peakpulse → PeakPulse │
└──────────────────────────────────────┬───────────────────────────────────────┘
│ │
┌──────────────────┐ ┌────────┴────────┐ ┌──────────────────────────────┐ ┌──────────────────────────────────────┴───────────────────────────────────────┐
│ LysnrAI Repo │ │ Common Platform │ │ MindLyst Repo │ │ learning_ai_common_plat │
│ (voice_ai_agent)│←─│ (common_plat) │─→│ (multimodal_memory_agents) │ │ 36 @bytelyst/* packages · 4 services · 3 dashboards · MCP/A2A orchestration │
│ │ │ @bytelyst/* │ │ │ │ platform-service · extraction-service · mcp-server · monitoring │
│ 4 Fastify svcs │ │ 8 npm packages │ │ KMP shared module │ │ admin-web · tracker-web · ux-lab │
│ 3 Next.js apps │ │ │ │ 3 native apps │ └──────────────────────────────────────┬───────────────────────────────────────┘
│ 1 FastAPI │ │ Design tokens │ │ 1 Next.js web │ │
│ 1 Desktop app │ │ (JSON → all) │ │ design-system/ │ ┌──────────────────────────────────────┴───────────────────────────────────────┐
│ 2 Mobile apps │ │ │ │ │ │ PRODUCT APPLICATION REPOSITORIES │
└────────┬─────────┘ └─────────────────┘ └──────────────┬───────────────┘ │ LysnrAI · MindLyst · ChronoMind · NomGap · JarvisJr · PeakPulse │
│ │ │ Each consumes shared packages/SDKs and owns product-specific apps/backends │
┌────────┴─────────────────────────────────────────────────┴───────────────┐ └──────────────────────────────────────┬───────────────────────────────────────┘
│ AZURE CLOUD INFRASTRUCTURE │ │
│ Cosmos DB · Blob Storage · Key Vault · Speech · OpenAI · Stripe │ ┌──────────────────────────────────────┴───────────────────────────────────────┐
│ Docker Compose (Traefik · Loki · Grafana) · GitHub Actions │ │ SHARED CLOUD / LOCAL PLATFORM INFRA │
└──────────────────────────────────────────────────────────────────────────┘ │ Cosmos DB · Blob Storage · Key Vault · OpenAI · Speech · Stripe │
│ Docker Compose · Traefik · Loki · Grafana · local repo workflows │
└──────────────────────────────────────────────────────────────────────────────┘
``` ```
--- ---
## 2. Three-Repo Structure ## 2. Workspace Structure
### 2.1 learning_voice_ai_agent (LysnrAI) The canonical repo list is maintained in `.windsurf/workflows/repos.txt` and currently includes seven active repositories.
**Purpose:** Cross-platform voice-to-text dictation platform. | Repository | Product / Role | Primary Stack | Key Capabilities |
| ----------------------------------- | -------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `learning_ai_common_plat` | Shared platform repo | TypeScript, Fastify, Next.js, Swift, Kotlin | 36 shared packages, platform-service, extraction-service, mcp-server, monitoring, admin-web, tracker-web, ux-lab |
| `learning_voice_ai_agent` | LysnrAI | Python 3.12, Fastify, Next.js, Swift, Kotlin | Desktop dictation, product backend, user dashboard, mobile apps |
| `learning_multimodal_memory_agents` | MindLyst | KMP, SwiftUI, Compose, Next.js | Shared business logic, native apps, web dashboard |
| `learning_ai_clock` | ChronoMind | Next.js, SwiftUI, Kotlin, Fastify | Timer/focus product, web + native + backend |
| `learning_ai_fastgap` | NomGap | React Native, Fastify | Fasting app, engine modules, Expo/mobile backend |
| `learning_ai_jarvis_jr` | JarvisJr | SwiftUI, Next.js, Kotlin, Fastify | Voice-first coaching apps and backend |
| `learning_ai_peakpulse` | PeakPulse | SwiftUI, Fastify | Sensor-driven adventure tracking app and backend |
| Component | Tech | Port | Description | ### 2.1 Role of `learning_ai_common_plat`
| --------------------- | -------------------- | ---- | ------------------------------------------------------ |
| Desktop App | Python 3.12, tkinter | — | macOS/Windows dictation app |
| FastAPI Backend | Python 3.12 | 8000 | REST API, cloud sync |
| platform-service | Fastify + TS | 4003 | Auth, audit, flags, notifications, blob, rate limiting |
| billing-service | Fastify + TS | 4002 | Subscriptions, plans, usage, licenses, Stripe |
| growth-service | Fastify + TS | 4001 | Invitations, referrals, promo codes |
| tracker-service | Fastify + TS | 4004 | Feature requests, bugs, votes, public roadmap |
| admin-dashboard-web | Next.js 16 | 3001 | Admin panel (users, tokens, audit, themes) |
| user-dashboard-web | Next.js 16 | 3002 | User portal (profile, billing, settings, SSO) |
| tracker-dashboard-web | Next.js | 3003 | Tracker board, kanban, public roadmap |
| iOS App | Swift + SwiftUI | — | Native (no KMP) |
| Android App | Kotlin + Compose | — | Native (no KMP) |
| Monitoring | Loki + Grafana | — | Health checks, logs, metrics |
### 2.2 learning_multimodal_memory_agents (MindLyst) **Purpose:** Shared platform foundation for all six product repositories.
**Purpose:** Role-based Life OS — multimodal second-brain with AI triage. | Surface | Current Scope |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Packages | 36 `@bytelyst/*` packages spanning auth, config, API clients, diagnostics, sync, storage, SDKs, design tokens, AI/extraction, and testing |
| Services | `platform-service` (4003), `extraction-service` (4005), `mcp-server`, `monitoring` |
| Dashboards | `admin-web` (3001), `tracker-web` (3003), `ux-lab` (internal) |
| Tooling | MCP tool registry, A2A pipelines, repo workflows, secret scanning, backup/sync automation |
| Component | Tech | Description | ### 2.2 Product Repositories
| ----------------- | --------------------- | -------------------------------------------------------- |
| KMP Shared Module | Kotlin Multiplatform | Models, repositories, DI, triage pipeline, API clients |
| iOS App | SwiftUI + KMP | Native UI consuming shared Kotlin module |
| Android App | Jetpack Compose + KMP | Native UI consuming shared Kotlin module |
| Web Dashboard | Next.js 14 | Pages Router, CSS custom properties, landing + dashboard |
| design-system/ | JSON + CSS | Canonical tokens, component specs |
### 2.3 learning_ai_common_plat (Common Platform) Each product repo consumes shared packages and/or SDKs from `learning_ai_common_plat` while owning product-specific UI, engine logic, and backend APIs.
**Purpose:** Shared npm packages consumed by both product repos. | Product | Repo | Shared Platform Consumption |
| ---------- | ----------------------------------- | ------------------------------------------------------------------------------------------- |
| LysnrAI | `learning_voice_ai_agent` | `@bytelyst/*` packages, shared platform-service, extraction-service, dashboards integration |
| MindLyst | `learning_multimodal_memory_agents` | design tokens, auth/config/cosmos patterns, extraction integration, platform-service |
| ChronoMind | `learning_ai_clock` | design tokens flow, platform-service, shared package patterns |
| NomGap | `learning_ai_fastgap` | React Native platform SDK and shared package integration |
| JarvisJr | `learning_ai_jarvis_jr` | shared SDKs/packages, platform-service, marketplace patterns |
| PeakPulse | `learning_ai_peakpulse` | Swift platform SDK, platform-service wrappers, shared design/system patterns |
| Package | Type | Primary Consumers | ### 2.3 Workspace Operating Model
| ------------------------- | ------------------- | -------------------------------------------------------- |
| `@bytelyst/errors` | TypeScript | All 4 Fastify services, dashboards | The workspace is managed as a coordinated multi-repo environment:
| `@bytelyst/cosmos` | TypeScript | All 4 Fastify services, 2 Next.js dashboards |
| `@bytelyst/config` | TypeScript | All 4 Fastify services | - Common platform changes land first when shared packages or services change.
| `@bytelyst/auth` | TypeScript | All services + dashboards with JWT | - Product repos consume `workspace:*` or `file:` references during local development.
| `@bytelyst/fastify-core` | TypeScript | All 4 Fastify services | - Cross-repo workflows (`repo_sync-repos`, `repo_backup-and-push`, `repo_commit-workspace`) use `.windsurf/workflows/repos.txt` as the canonical repo list.
| `@bytelyst/api-client` | TypeScript | All 3 Next.js dashboards | - MCP/A2A capabilities in `services/mcp-server` provide orchestration and operator tooling across the workspace.
| `@bytelyst/react-auth` | TypeScript/React | All 3 Next.js dashboards |
| `@bytelyst/design-tokens` | JSON → multi-format | MindLyst (all platforms), potentially LysnrAI dashboards | ### 2.4 Historical Note
Older sections of this document may describe the earlier three-repo architecture used during the initial refactor phase. The current source of truth for active workspace topology is the seven-repo model above.
--- ---

64
docs/learning_ai_common_plat_INVENTORY.md
View File

@ -2,17 +2,17 @@
> **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-03 > **Last Updated:** 2026-03-05
--- ---
## 1. Quick Stats ## 1. Quick Stats
| Category | Count | Notes | | Category | Count | Notes |
| --------------------- | ------- | ----------------------------------------------------- | | --------------------- | ------- | -------------------------------------------------------------------- |
| **Shared Packages** | 32 | `@bytelyst/*` — consumed via `file:` or `workspace:*` | | **Shared Packages** | 36 | `@bytelyst/*` — consumed via `file:` or `workspace:*` |
| **Platform Services** | 2 | Running services (consolidated from 5) | | **Platform Services** | 4 | `platform-service`, `extraction-service`, `mcp-server`, `monitoring` |
| **Dashboards** | 2 | Product-agnostic web consoles | | **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 | | **Cosmos Containers** | ~50+ | Shared + product-specific |
| **Total Tests** | ~1,700+ | Service + package + SDK tests | | **Total Tests** | ~1,700+ | Service + package + SDK tests |
@ -80,13 +80,21 @@
| `@bytelyst/llm` | LLM utilities | Prompt templates, token counting | Services | | `@bytelyst/llm` | LLM utilities | Prompt templates, token counting | Services |
| `@bytelyst/speech` | Speech SDK wrappers | Azure Speech integration | Desktop + Mobile | | `@bytelyst/speech` | Speech SDK wrappers | Azure Speech integration | Desktop + Mobile |
### 2.7 Design System ### 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 | | 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 |
### 2.8 React Native ### 2.9 React Native
| Package | Purpose | Exports | Consumers | | Package | Purpose | Exports | Consumers |
| ------------------------------------- | --------------- | ---------------------------------------- | ----------------------- | | ------------------------------------- | --------------- | ---------------------------------------- | ----------------------- |
@ -102,9 +110,11 @@ Consolidated from billing-service, growth-service, tracker-service.
**Status:** Active | **Tests:** ~1,050+ | **Modules:** 45 **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 | | Module | Purpose | Cosmos Container | Public API |
| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------- | | ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- |
| **auth** | JWT issue/refresh, password reset, email verification | `users`, `password_reset_tokens`, `email_verifications` | `/auth/*` | | **auth** | JWT issue/refresh, password reset, email verification | `users`, `password_reset_tokens`, `email_verifications` | `/api/auth/*` |
| **audit** | Audit logging | `audit_log` | Admin only | | **audit** | Audit logging | `audit_log` | Admin only |
| **blob** | Azure Blob Storage | - | `/api/blob/*` | | **blob** | Azure Blob Storage | - | `/api/blob/*` |
| **broadcasts** | Feature announcements | `broadcasts` | Admin: CRUD, Public: read | | **broadcasts** | Feature announcements | `broadcasts` | Admin: CRUD, Public: read |
@ -139,13 +149,13 @@ Consolidated from billing-service, growth-service, tracker-service.
| **votes** | Item voting | `votes` | `/votes/*` | | **votes** | Item voting | `votes` | `/votes/*` |
| **waitlist** | Pre-launch signup | `waitlist` | `/waitlist/*` | | **waitlist** | Pre-launch signup | `waitlist` | `/waitlist/*` |
| **webhooks** | Webhook subscriptions | `webhook_subscriptions`, `webhook_deliveries` | `/webhooks/*` | | **webhooks** | Webhook subscriptions | `webhook_subscriptions`, `webhook_deliveries` | `/webhooks/*` |
| **ab-testing** | A/B experiments | `experiments`, `experiment_assignments` | `/experiments/*` | | **ab-testing** | A/B experiments | `experiments`, `experiment_assignments` | `/api/ab-testing/*` |
| **predictive-analytics** | Churn/health scoring | `predictive_scores`, `score_history` | `/predictive/*` | | **predictive-analytics** | Churn/health scoring | `predictive_scores`, `score_history` | `/api/predictive-analytics/*` |
| **analytics** | Analytics rollups | `analytics_events`, `analytics_aggregates` | `/analytics/*` | | **analytics** | Analytics rollups | `analytics_events`, `analytics_aggregates` | `/analytics/*` |
| **exports** | GDPR data export | `export_jobs` | `/exports/*` | | **exports** | GDPR data export | `export_jobs` | `/exports/*` |
| **feedback** | In-app feedback | `feedback` | `/feedback/*` | | **feedback** | In-app feedback | `feedback` | `/feedback/*` |
| **impersonation** | User impersonation | `impersonation_sessions` | `/impersonation/*` | | **impersonation** | User impersonation | `impersonation_sessions` | `/impersonation/*` |
| **changelog** | Product changelogs | `changelogs` | `/changelogs/*` | | **changelog** | Product changelogs | `changelogs` | `/api/changelog`, `/api/admin/changelog` |
| **ratelimit** | Rate limiting | `rate_limit_windows` | `/ratelimit/*` | | **ratelimit** | Rate limiting | `rate_limit_windows` | `/ratelimit/*` |
### 3.2 extraction-service (Port 4005) ### 3.2 extraction-service (Port 4005)
@ -157,6 +167,27 @@ 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)
**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. Dashboards (Product-Agnostic)
@ -196,6 +227,15 @@ Consolidated from billing-service, growth-service, tracker-service.
| Item Detail | `/items/:id` | Discussion + voting | | Item Detail | `/items/:id` | Discussion + voting |
| Submit | `/submit` | New feature request | | 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. Platform SDKs