# ByteLyst Common Platform

> Shared packages and microservices for ByteLyst ecosystem products.

## ⚠️ GitHub Actions Temporarily Disabled

CI/CD is currently disabled due to billing issues. Please run manual quality checks before merging:

- See [MANUAL_CI.md](./MANUAL_CI.md) for instructions
- Use `.windsurf/workflows/production-readiness.md` for comprehensive checks

## 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
pnpm test

# Type-check all packages
pnpm typecheck

# Run a specific service in dev mode
pnpm --filter @lysnrai/platform-service dev
```

## Prototype Deployment

For a single-host prototype, use Docker Compose with the repo root [`docker-compose.yml`](/root/bytelyst.ai/repos/learning_ai_common_plat/docker-compose.yml).

```bash
cp .env.example .env
./scripts/prototype-up.sh
pnpm prototype:self-test
```

See [docs/PROTOTYPE_DEPLOYMENT.md](docs/PROTOTYPE_DEPLOYMENT.md) for the required environment variables and day-to-day commands.

The prototype stack now includes a local Cosmos DB Emulator container, so the default `.env.example` values are wired for single-VM Docker use.
Blob uploads are backed by local Azurite, prototype email delivery is backed by Mailpit, and the platform exposes prototype diagnostics at `/api/health/dependencies`, `/api/self-test`, and `/api/self-test.json`.

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

## Ecosystem Docs

Cross-product strategy and shared-contract documentation now lives under [`docs/ecosystem/`](/Users/saravana/BytelystAI/learning_ai/learning_ai_common_plat/docs/ecosystem).

## Repository Structure

```
learning_ai_common_plat/
├── 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)
│   └── 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
```

## Package Families

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

## Services and Dashboards

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

## Consuming Libraries from Product Repos

During development, use `file:` references in consumer `package.json`:

```jsonc
// From a Next.js dashboard at repo root (2 levels up):
"@bytelyst/errors": "file:../../learning_ai_common_plat/packages/errors"

// From MindLyst web (3 levels up — inside mindlyst-native/web/):
"@bytelyst/design-tokens": "file:../../../learning_ai_common_plat/packages/design-tokens"
```

All repos must be cloned side-by-side under the same parent directory.

### Portable Builds (Docker / CI)

`file:` refs break in Docker and CI because the sibling repo isn't available at the expected relative path. Use the **tarball prep** workflow to make builds self-contained:

```bash
# 1. Build all @bytelyst/* packages
pnpm build

# 2. Pack tarballs + rewrite a consumer's package.json
#    (run from the consumer repo)
../learning_ai_common_plat/scripts/prep-consumer.sh <target-dir>

# 3. Build (Docker, EAS, CI — no sibling repo access needed)
docker build <target-dir>

# 4. Restore original package.json
../learning_ai_common_plat/scripts/prep-consumer.sh <target-dir> --restore
```

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

> **Dashboards inside this repo** (`dashboards/admin-web`, `dashboards/tracker-web`) use `workspace:*` refs and do NOT need this workflow — pnpm resolves them automatically.

## Infrastructure Lint

Validates all 25 Dockerfiles across the 11 ByteLyst repos using [hadolint](https://github.com/hadolint/hadolint), and any Helm charts using `helm lint` + `helm template`.

```bash
# Prerequisites
brew install hadolint helm

# Lint everything
./scripts/lint-infra.sh

# Dockerfiles only / Helm charts only
./scripts/lint-infra.sh --docker
./scripts/lint-infra.sh --helm

# Explicit paths
./scripts/lint-infra.sh path/to/Dockerfile path/to/chart-dir
```

Suppressed rules (false positives for this codebase): `DL3045`, `DL3018`, `DL3008`, `DL3059`, `SC2155`.

## Design Tokens

Generate platform-specific token files from the canonical JSON:

```bash
cd packages/design-tokens
pnpm generate
```

Outputs in `packages/design-tokens/generated/`:

- `tokens.css` — CSS custom properties (`--ml-*`)
- `tokens.ts` — TypeScript constants
- `MindLystTokens.kt` — Kotlin object for KMP
- `MindLystTheme.swift` — Swift structs for SwiftUI

## Roadmap

See [docs/ROADMAP.md](docs/ROADMAP.md) for the full phased extraction plan.
