# @bytelyst/common-platform

Shared packages **and** product-agnostic microservices for the ByteLyst ecosystem — used by [LysnrAI](https://github.com/saravanakumardb1/learning_voice_ai_agent) and [MindLyst](https://github.com/saravanakumardb1/learning_multimodal_memory_agents).

## 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)
├── services/                    # Product-agnostic microservices
│   ├── platform-service/        # Auth, audit, flags, notifications, blob (port 4003)
│   ├── billing-service/         # Subscriptions, Stripe, usage, licenses (port 4002)
│   ├── growth-service/          # Invitations, referrals, promos (port 4001)
│   ├── tracker-service/         # Items, comments, votes, public roadmap (port 4004)
│   └── 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/cosmos` | Azure Cosmos DB client singleton + container registry | `@azure/cosmos` |
| `@bytelyst/config` | Zod-based env config loader + product identity | `zod` |
| `@bytelyst/auth` | JWT utilities, auth middleware, password hashing | `jose`, `bcryptjs` |
| `@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) | — |

## Shared Services

| Service | Port | Description | Tests |
|---------|------|-------------|-------|
| `platform-service` | 4003 | Auth, audit, feature flags, notifications, blob storage | 55 |
| `billing-service` | 4002 | Subscriptions, Stripe webhooks, usage tracking, licenses, plans | 32 |
| `growth-service` | 4001 | Invitations, referrals, promo codes | 33 |
| `tracker-service` | 4004 | Feature requests, bugs, tasks, public roadmap | 45 |
| `monitoring` | — | Loki + Grafana dashboards, health-check script | — |

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

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