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

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)
│   ├── 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)
│   ├── extraction-service/      # LangExtract text extraction + Python sidecar (port 4005)
│   └── monitoring/              # Loki + Grafana config, health-check
└── docs/                        # Architecture docs, roadmap, analysis

Shared Libraries

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	—

Shared Services

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	—

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

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

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

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.