179 lines
10 KiB
Markdown
179 lines
10 KiB
Markdown
# 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
|
|
```
|
|
|
|
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.
|
|
|
|
## 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/ # 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.
|
|
|
|
## 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.
|