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

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