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 for instructions
• Use .windsurf/workflows/production-readiness.md for comprehensive checks

Quick Start

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

cp .env.example .env
./scripts/prototype-up.sh
pnpm prototype:self-test
pnpm docker:clean

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

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:

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

# 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, and any Helm charts using helm lint + helm template.

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

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 for the full phased extraction plan.