From 8f63713c52d056e3a7c9bd22bdd4280f1d3cee78 Mon Sep 17 00:00:00 2001 From: saravanakumardb1 Date: Thu, 5 Mar 2026 22:59:45 -0800 Subject: [PATCH] docs(inventory): refresh platform and workspace capability maps --- README.md | 121 ++++++++-------- docs/WORKSPACE_INVENTORY.md | 97 +++++++++++++ docs/architecture/ECOSYSTEM_ARCHITECTURE.md | 136 ++++++++++-------- docs/learning_ai_common_plat_INVENTORY.md | 152 ++++++++++++-------- 4 files changed, 324 insertions(+), 182 deletions(-) create mode 100644 docs/WORKSPACE_INVENTORY.md diff --git a/README.md b/README.md index 72f681c4..293535f2 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ pnpm build # Quick quality check (5 min) - run before pushing! ./quick-check.sh -# Run all tests (165 total across packages + services) +# Run all tests pnpm test # Type-check all packages @@ -31,80 +31,75 @@ pnpm typecheck 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 ``` learning_ai_common_plat/ -├── packages/ # Shared libraries (@bytelyst/*) -│ ├── errors/ # Typed HTTP service errors (400–429) -│ ├── cosmos/ # Azure Cosmos DB client + container registry -│ ├── config/ # Zod env loader + product identity -│ ├── auth/ # JWT, middleware, password hashing -│ ├── api-client/ # Configurable fetch wrapper -│ ├── react-auth/ # React auth context factory -│ └── design-tokens/ # Cross-platform tokens (JSON → CSS/TS/Kotlin/Swift) -├── dashboards/ # Product-agnostic web dashboards (Next.js) +├── packages/ # 36 shared libraries (@bytelyst/*) +│ ├── api-client/ +│ ├── auth/ +│ ├── auth-client/ +│ ├── blob/ + blob-client/ +│ ├── broadcast-client/ + survey-client/ +│ ├── config/ + cosmos/ +│ ├── dashboard-components/ +│ ├── 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) -│ └── tracker-web/ # Issue tracker + public roadmap (port 3003) -├── services/ # Product-agnostic microservices -│ ├── platform-service/ # Consolidated: auth, audit, flags, billing, growth, tracker (port 4003) +│ ├── tracker-web/ # Issue tracker + public roadmap (port 3003) +│ └── ux-lab/ # Internal UX lab / MCP-assisted ops prototypes +├── services/ # Platform services + tooling servers +│ ├── platform-service/ # Product-agnostic platform API (port 4003) │ ├── extraction-service/ # LangExtract text extraction + Python sidecar (port 4005) +│ ├── mcp-server/ # MCP tool server + A2A orchestration │ └── monitoring/ # Loki + Grafana config, health-check └── docs/ # Architecture docs, roadmap, analysis ``` -## Shared Libraries +## Package Families -| Package | Description | Peer Dependencies | -| ------------------------- | --------------------------------------------------------- | ---------------------- | -| `@bytelyst/errors` | Typed HTTP service errors (400–429) | — | -| `@bytelyst/logger` | Structured logger factory for services/dashboards | — | -| `@bytelyst/cosmos` | Azure Cosmos DB client singleton + container registry | `@azure/cosmos` | -| `@bytelyst/blob` | Azure Blob Storage helpers + SAS URL generation | `@azure/storage-blob` | -| `@bytelyst/config` | Zod-based env config loader + product identity | `zod` | -| `@bytelyst/auth` | JWT utilities, auth middleware, password hashing | `jose`, `bcryptjs` | -| `@bytelyst/fastify-core` | Fastify service bootstrap (request-id, /health, errors) | `fastify` | -| `@bytelyst/api-client` | Configurable fetch wrapper with auth token injection | — | -| `@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 | — | +| Family | Representative Packages | Purpose | +| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------- | +| Core platform | `@bytelyst/config`, `@bytelyst/cosmos`, `@bytelyst/errors`, `@bytelyst/logger`, `@bytelyst/testing` | Shared infrastructure for all services and dashboards | +| Auth & app clients | `@bytelyst/auth`, `@bytelyst/auth-client`, `@bytelyst/api-client`, `@bytelyst/platform-client`, `@bytelyst/react-auth` | Identity, auth flows, typed service clients | +| Diagnostics & telemetry | `@bytelyst/diagnostics-client`, `@bytelyst/telemetry-client`, `@bytelyst/swift-diagnostics` | Client diagnostics, event batching, crash/error capture | +| Storage & sync | `@bytelyst/blob`, `@bytelyst/blob-client`, `@bytelyst/datastore`, `@bytelyst/storage`, `@bytelyst/sync`, `@bytelyst/offline-queue` | Blob, local persistence, sync orchestration | +| 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 | +| AI & extraction | `@bytelyst/extraction`, `@bytelyst/llm`, `@bytelyst/speech` | Extraction tasks, LLM utilities, speech integration | +| UI & design | `@bytelyst/design-tokens`, `@bytelyst/dashboard-components` | Shared tokens and dashboard UI building blocks | +| Native SDKs | `@bytelyst/swift-platform-sdk`, `@bytelyst/kotlin-platform-sdk`, `@bytelyst/react-native-platform-sdk` | Cross-platform mobile/native platform access | -## Shared Services +## Services and Dashboards -| Service | Port | Description | Tests | -| -------------------- | ---- | ------------------------------------------------------------------------------ | ------ | -| `platform-service` | 4003 | Consolidated: auth, audit, flags, billing, growth, tracker, telemetry, etc. | 1,029 | -| `extraction-service` | 4005 | LangExtract text extraction + Python sidecar | 46 | -| `monitoring` | — | Loki + Grafana dashboards, health-check script | — | +| Surface | Port | Description | +| -------------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `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-based extraction service with task library and Python sidecar | +| `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). 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 During development, use `file:` references in consumer `package.json`: @@ -140,12 +135,12 @@ docker build Each consumer repo has a convenience wrapper: `scripts/docker-prep.sh` (or `scripts/docker-prep-dashboards.sh` in LysnrAI). -| Consumer Repo | Wrapper Script | Targets | -|---------------|---------------|---------| -| `learning_voice_ai_agent` | `scripts/docker-prep-dashboards.sh` | `user-dashboard-web` | -| `learning_ai_clock` | `scripts/docker-prep.sh` | `web` | -| `learning_ai_fastgap` | `scripts/docker-prep.sh` | root `package.json` | -| `learning_multimodal_memory_agents` | `scripts/docker-prep.sh` | `mindlyst-native/web` | +| Consumer Repo | Wrapper Script | Targets | +| ----------------------------------- | ----------------------------------- | --------------------- | +| `learning_voice_ai_agent` | `scripts/docker-prep-dashboards.sh` | `user-dashboard-web` | +| `learning_ai_clock` | `scripts/docker-prep.sh` | `web` | +| `learning_ai_fastgap` | `scripts/docker-prep.sh` | root `package.json` | +| `learning_multimodal_memory_agents` | `scripts/docker-prep.sh` | `mindlyst-native/web` | > **Dashboards inside this repo** (`dashboards/admin-web`, `dashboards/tracker-web`) use `workspace:*` refs and do NOT need this workflow — pnpm resolves them automatically. diff --git a/docs/WORKSPACE_INVENTORY.md b/docs/WORKSPACE_INVENTORY.md new file mode 100644 index 00000000..647a2ada --- /dev/null +++ b/docs/WORKSPACE_INVENTORY.md @@ -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. diff --git a/docs/architecture/ECOSYSTEM_ARCHITECTURE.md b/docs/architecture/ECOSYSTEM_ARCHITECTURE.md index 600f9f9f..4a837db9 100644 --- a/docs/architecture/ECOSYSTEM_ARCHITECTURE.md +++ b/docs/architecture/ECOSYSTEM_ARCHITECTURE.md @@ -2,14 +2,14 @@ > **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 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) 4. [Component & Service Inventory](#4-component--service-inventory) 5. [Dependency Graph](#5-dependency-graph) @@ -25,82 +25,92 @@ ## 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 │ -│ LysnrAI Desktop · iOS · Android · Admin · User Portal · Tracker │ -│ MindLyst iOS · Android · Web │ -└───────────────────────────────┬──────────────────────────────────────────┘ - │ -┌──────────────────┐ ┌────────┴────────┐ ┌──────────────────────────────┐ -│ LysnrAI Repo │ │ Common Platform │ │ MindLyst Repo │ -│ (voice_ai_agent)│←─│ (common_plat) │─→│ (multimodal_memory_agents) │ -│ │ │ @bytelyst/* │ │ │ -│ 4 Fastify svcs │ │ 8 npm packages │ │ KMP shared module │ -│ 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 │ │ │ │ │ -└────────┬─────────┘ └─────────────────┘ └──────────────┬───────────────┘ - │ │ -┌────────┴─────────────────────────────────────────────────┴───────────────┐ -│ AZURE CLOUD INFRASTRUCTURE │ -│ Cosmos DB · Blob Storage · Key Vault · Speech · OpenAI · Stripe │ -│ Docker Compose (Traefik · Loki · Grafana) · GitHub Actions │ -└──────────────────────────────────────────────────────────────────────────┘ +┌──────────────────────────────────────────────────────────────────────────────┐ +│ ACTIVE WORKSPACE REPOS │ +│ learning_ai_common_plat → shared packages, services, dashboards, MCP │ +│ 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 │ +└──────────────────────────────────────┬───────────────────────────────────────┘ + │ +┌──────────────────────────────────────┴───────────────────────────────────────┐ +│ learning_ai_common_plat │ +│ 36 @bytelyst/* packages · 4 services · 3 dashboards · MCP/A2A orchestration │ +│ platform-service · extraction-service · mcp-server · monitoring │ +│ admin-web · tracker-web · ux-lab │ +└──────────────────────────────────────┬───────────────────────────────────────┘ + │ +┌──────────────────────────────────────┴───────────────────────────────────────┐ +│ PRODUCT APPLICATION REPOSITORIES │ +│ LysnrAI · MindLyst · ChronoMind · NomGap · JarvisJr · PeakPulse │ +│ Each consumes shared packages/SDKs and owns product-specific apps/backends │ +└──────────────────────────────────────┬───────────────────────────────────────┘ + │ +┌──────────────────────────────────────┴───────────────────────────────────────┐ +│ 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 | -| --------------------- | -------------------- | ---- | ------------------------------------------------------ | -| 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.1 Role of `learning_ai_common_plat` -### 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 | -| ----------------- | --------------------- | -------------------------------------------------------- | -| 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.2 Product Repositories -### 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 | -| ------------------------- | ------------------- | -------------------------------------------------------- | -| `@bytelyst/errors` | TypeScript | All 4 Fastify services, dashboards | -| `@bytelyst/cosmos` | TypeScript | All 4 Fastify services, 2 Next.js dashboards | -| `@bytelyst/config` | TypeScript | All 4 Fastify services | -| `@bytelyst/auth` | TypeScript | All services + dashboards with JWT | -| `@bytelyst/fastify-core` | TypeScript | All 4 Fastify services | -| `@bytelyst/api-client` | TypeScript | All 3 Next.js dashboards | -| `@bytelyst/react-auth` | TypeScript/React | All 3 Next.js dashboards | -| `@bytelyst/design-tokens` | JSON → multi-format | MindLyst (all platforms), potentially LysnrAI dashboards | +### 2.3 Workspace Operating Model + +The workspace is managed as a coordinated multi-repo environment: + +- Common platform changes land first when shared packages or services change. +- Product repos consume `workspace:*` or `file:` references during local development. +- Cross-repo workflows (`repo_sync-repos`, `repo_backup-and-push`, `repo_commit-workspace`) use `.windsurf/workflows/repos.txt` as the canonical repo list. +- MCP/A2A capabilities in `services/mcp-server` provide orchestration and operator tooling across the workspace. + +### 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. --- diff --git a/docs/learning_ai_common_plat_INVENTORY.md b/docs/learning_ai_common_plat_INVENTORY.md index 9a8291f4..a3b7145d 100644 --- a/docs/learning_ai_common_plat_INVENTORY.md +++ b/docs/learning_ai_common_plat_INVENTORY.md @@ -2,20 +2,20 @@ > **Purpose:** Comprehensive reference for all reusable components, services, SDKs, and tools available to ByteLyst product teams. > **Repo:** `learning_ai_common_plat` -> **Last Updated:** 2026-03-03 +> **Last Updated:** 2026-03-05 --- ## 1. Quick Stats -| Category | Count | Notes | -| --------------------- | ------- | ----------------------------------------------------- | -| **Shared Packages** | 32 | `@bytelyst/*` — consumed via `file:` or `workspace:*` | -| **Platform Services** | 2 | Running services (consolidated from 5) | -| **Dashboards** | 2 | Product-agnostic web consoles | -| **Platform SDKs** | 3 | Swift, Kotlin, React Native | -| **Cosmos Containers** | ~50+ | Shared + product-specific | -| **Total Tests** | ~1,700+ | Service + package + SDK tests | +| Category | Count | Notes | +| --------------------- | ------- | -------------------------------------------------------------------- | +| **Shared Packages** | 36 | `@bytelyst/*` — consumed via `file:` or `workspace:*` | +| **Platform Services** | 4 | `platform-service`, `extraction-service`, `mcp-server`, `monitoring` | +| **Dashboards** | 3 | `admin-web`, `tracker-web`, `ux-lab` | +| **Platform SDKs** | 3 | Swift, Kotlin, React Native | +| **Cosmos Containers** | ~50+ | Shared + product-specific | +| **Total Tests** | ~1,700+ | Service + package + SDK tests | --- @@ -80,13 +80,21 @@ | `@bytelyst/llm` | LLM utilities | Prompt templates, token counting | Services | | `@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 | | ------------------------- | --------------------- | --------------------------------- | ------------- | | `@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 | | ------------------------------------- | --------------- | ---------------------------------------- | ----------------------- | @@ -102,51 +110,53 @@ Consolidated from billing-service, growth-service, tracker-service. **Status:** Active | **Tests:** ~1,050+ | **Modules:** 45 -| Module | Purpose | Cosmos Container | Public API | -| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------- | ------------------------- | -| **auth** | JWT issue/refresh, password reset, email verification | `users`, `password_reset_tokens`, `email_verifications` | `/auth/*` | -| **audit** | Audit logging | `audit_log` | Admin only | -| **blob** | Azure Blob Storage | - | `/api/blob/*` | -| **broadcasts** | Feature announcements | `broadcasts` | Admin: CRUD, Public: read | -| **comments** | Item comments | `comments` | `/comments/*` | -| **delivery** | Email/push delivery | `delivery_log`, templates | Internal | -| **diagnostics** | Remote diagnostics, error clustering | `diagnostic_sessions`, `error_clusters` | `/diagnostics/*` | -| **ai-diagnostics** | AI-powered diagnostic assistant | `auto_triggers`, `diagnostic_sessions` | `/ai-diagnostics/*` | -| **flags** | Feature flags | `feature_flags` | `/flags/poll` (client) | -| **invitations** | Team invitations | `invitations` | `/invitations/*` | -| **ip-rules** | IP allow/deny | `ip_rules` | Admin only | -| **items** | Tracker items | `items` | `/items/*` | -| **jobs** | Scheduled job runner | `job_definitions`, `job_runs` | Admin only | -| **licenses** | License key management | `licenses` | `/licenses/*` | -| **maintenance** | Maintenance mode | `maintenance_windows` | Admin only | -| **marketplace** | Product marketplace (JarvisJr) | `marketplace_listings`, `purchases` | `/marketplace/*` | -| **notifications** | Push/email triggers | `notification_queue` | Internal | -| **plans** | Subscription plans | `plans` | `/plans/*` | -| **products** | Product registry | `products` | Admin only | -| **promos** | Promo codes | `promos` | `/promos/*` | -| **public** | Public endpoints (no auth) | - | `/public/*` | -| **referrals** | Referral system | `referrals` | `/referrals/*` | -| **sessions** | Device session management | `sessions` | `/sessions/*` | -| **settings** | Platform settings | `settings` | Admin only | -| **status** | Public status page | `incidents` | `/status/*` (public read) | -| **stripe** | Stripe webhooks | - | `/stripe/webhook` | -| **subscriptions** | Subscriptions | `subscriptions` | `/subscriptions/*` | -| **surveys** | User surveys | `surveys`, `survey_responses` | `/surveys/*` | -| **telemetry** | Client telemetry ingestion | `telemetry_events`, `telemetry_error_clusters`, `telemetry_collection_policies` | `/telemetry/*` | -| **themes** | Platform themes | `themes` | `/themes/*` | -| **tokens** | API tokens | `api_tokens` | `/tokens/*` | -| **usage** | Usage tracking | `usage_daily`, `usage_hourly` | `/usage/*` | -| **votes** | Item voting | `votes` | `/votes/*` | -| **waitlist** | Pre-launch signup | `waitlist` | `/waitlist/*` | -| **webhooks** | Webhook subscriptions | `webhook_subscriptions`, `webhook_deliveries` | `/webhooks/*` | -| **ab-testing** | A/B experiments | `experiments`, `experiment_assignments` | `/experiments/*` | -| **predictive-analytics** | Churn/health scoring | `predictive_scores`, `score_history` | `/predictive/*` | -| **analytics** | Analytics rollups | `analytics_events`, `analytics_aggregates` | `/analytics/*` | -| **exports** | GDPR data export | `export_jobs` | `/exports/*` | -| **feedback** | In-app feedback | `feedback` | `/feedback/*` | -| **impersonation** | User impersonation | `impersonation_sessions` | `/impersonation/*` | -| **changelog** | Product changelogs | `changelogs` | `/changelogs/*` | -| **ratelimit** | Rate limiting | `rate_limit_windows` | `/ratelimit/*` | +**Route Note:** Route families below are shown in their deployed form. Most are registered under the `/api` prefix unless explicitly public. + +| Module | Purpose | Cosmos Container | Public API | +| ------------------------ | ----------------------------------------------------- | ------------------------------------------------------------------------------- | ---------------------------------------- | +| **auth** | JWT issue/refresh, password reset, email verification | `users`, `password_reset_tokens`, `email_verifications` | `/api/auth/*` | +| **audit** | Audit logging | `audit_log` | Admin only | +| **blob** | Azure Blob Storage | - | `/api/blob/*` | +| **broadcasts** | Feature announcements | `broadcasts` | Admin: CRUD, Public: read | +| **comments** | Item comments | `comments` | `/comments/*` | +| **delivery** | Email/push delivery | `delivery_log`, templates | Internal | +| **diagnostics** | Remote diagnostics, error clustering | `diagnostic_sessions`, `error_clusters` | `/diagnostics/*` | +| **ai-diagnostics** | AI-powered diagnostic assistant | `auto_triggers`, `diagnostic_sessions` | `/ai-diagnostics/*` | +| **flags** | Feature flags | `feature_flags` | `/flags/poll` (client) | +| **invitations** | Team invitations | `invitations` | `/invitations/*` | +| **ip-rules** | IP allow/deny | `ip_rules` | Admin only | +| **items** | Tracker items | `items` | `/items/*` | +| **jobs** | Scheduled job runner | `job_definitions`, `job_runs` | Admin only | +| **licenses** | License key management | `licenses` | `/licenses/*` | +| **maintenance** | Maintenance mode | `maintenance_windows` | Admin only | +| **marketplace** | Product marketplace (JarvisJr) | `marketplace_listings`, `purchases` | `/marketplace/*` | +| **notifications** | Push/email triggers | `notification_queue` | Internal | +| **plans** | Subscription plans | `plans` | `/plans/*` | +| **products** | Product registry | `products` | Admin only | +| **promos** | Promo codes | `promos` | `/promos/*` | +| **public** | Public endpoints (no auth) | - | `/public/*` | +| **referrals** | Referral system | `referrals` | `/referrals/*` | +| **sessions** | Device session management | `sessions` | `/sessions/*` | +| **settings** | Platform settings | `settings` | Admin only | +| **status** | Public status page | `incidents` | `/status/*` (public read) | +| **stripe** | Stripe webhooks | - | `/stripe/webhook` | +| **subscriptions** | Subscriptions | `subscriptions` | `/subscriptions/*` | +| **surveys** | User surveys | `surveys`, `survey_responses` | `/surveys/*` | +| **telemetry** | Client telemetry ingestion | `telemetry_events`, `telemetry_error_clusters`, `telemetry_collection_policies` | `/telemetry/*` | +| **themes** | Platform themes | `themes` | `/themes/*` | +| **tokens** | API tokens | `api_tokens` | `/tokens/*` | +| **usage** | Usage tracking | `usage_daily`, `usage_hourly` | `/usage/*` | +| **votes** | Item voting | `votes` | `/votes/*` | +| **waitlist** | Pre-launch signup | `waitlist` | `/waitlist/*` | +| **webhooks** | Webhook subscriptions | `webhook_subscriptions`, `webhook_deliveries` | `/webhooks/*` | +| **ab-testing** | A/B experiments | `experiments`, `experiment_assignments` | `/api/ab-testing/*` | +| **predictive-analytics** | Churn/health scoring | `predictive_scores`, `score_history` | `/api/predictive-analytics/*` | +| **analytics** | Analytics rollups | `analytics_events`, `analytics_aggregates` | `/analytics/*` | +| **exports** | GDPR data export | `export_jobs` | `/exports/*` | +| **feedback** | In-app feedback | `feedback` | `/feedback/*` | +| **impersonation** | User impersonation | `impersonation_sessions` | `/impersonation/*` | +| **changelog** | Product changelogs | `changelogs` | `/api/changelog`, `/api/admin/changelog` | +| **ratelimit** | Rate limiting | `rate_limit_windows` | `/ratelimit/*` | ### 3.2 extraction-service (Port 4005) @@ -157,6 +167,27 @@ Consolidated from billing-service, growth-service, tracker-service. | **extract** | Text extraction (LangExtract) | Python + TypeScript hybrid | | **tasks** | Extraction task management | TypeScript | +### 3.3 mcp-server (Tooling + A2A orchestration) + +**Status:** Active | **Primary Role:** Tool registry + MCP tool execution + A2A orchestration layer + +| Namespace / Area | Purpose | Surface | +| ---------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------------------- | +| **tools** | Tool registry, schema exposure, execution routing | `/api/tools`, `/api/tools/call` | +| **platform** | Admin/operator tools for telemetry, diagnostics, secrets, experiments, SDK, webhooks, ops | MCP tools | +| **extraction** | MCP wrappers for extraction workflows | MCP tools | +| **a2a** | Cross-product agent-to-agent pipelines and orchestration flows | Pipeline tools | +| **dev** | Changelog generation, synthetic data generation, internal dev tooling | MCP tools | +| **product namespaces** | Product-specific tool entry points for LysnrAI, JarvisJr, ChronoMind, NomGap, PeakPulse, MindLyst, tracker | MCP tools | + +### 3.4 monitoring + +| Component | Purpose | Surface | +| ---------------- | ---------------------------------- | ------------------ | +| **health-check** | Local service health aggregation | CLI / script | +| **loki** | Structured log aggregation | Docker/local infra | +| **grafana** | Dashboards and observability views | Docker/local infra | + --- ## 4. Dashboards (Product-Agnostic) @@ -196,6 +227,15 @@ Consolidated from billing-service, growth-service, tracker-service. | Item Detail | `/items/:id` | Discussion + voting | | Submit | `/submit` | New feature request | +### 4.3 ux-lab + +**Stack:** Experimental/internal dashboard workbench for operations UI kits, scoped prototypes, and MCP-driven UX workflows. + +| Area | Description | +| ------------------ | ---------------------------------------------------------------------------------- | +| `bolt-ops-ui-kit/` | Internal UI kit and scoping docs for ops/dashboard work | +| Prototypes | Workspace for UX exploration, MCP-assisted workflows, and internal experimentation | + --- ## 5. Platform SDKs