171 lines
7.3 KiB
Markdown
171 lines
7.3 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 (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
|
||
|
||
```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 (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`:
|
||
|
||
```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.
|