# 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 # 3. Build (Docker, EAS, CI — no sibling repo access needed) docker build # 4. Restore original package.json ../learning_ai_common_plat/scripts/prep-consumer.sh --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.