learning_ai_common_plat/AI.dev/PROMPTS/platform-integration.md

---
name: platform-integration
description: 'Wire a product repo into the ByteLyst common platform ecosystem — auth, flags, telemetry, design tokens, and shared packages.'
argument-hint: 'Product repo name and integration scope, e.g. "learning_ai_efforise — full integration", "learning_ai_peakpulse — auth + flags only"'
agent: agent
---

# Platform Integration Prompt

Connect a product repository to the ByteLyst common platform, wiring up auth, feature flags, telemetry, design tokens, and shared packages.

## Context — Integration Architecture

```
Product Repo (e.g. learning_ai_efforise)
├── backend/  ──→  @bytelyst/fastify-core, config, errors, datastore, auth, fastify-auth
├── web/      ──→  @bytelyst/react-auth, api-client, design-tokens, ui, feature-flag-client
├── mobile/   ──→  @bytelyst/auth-client, telemetry-client, feature-flag-client
└── shared/product.json  ──→  Product identity consumed by all layers
            │
            ▼
    platform-service (port 4003)
    ├── Auth (JWT issue/validate)
    ├── Feature flags (FNV-1a rollout)
    ├── Telemetry (event ingestion)
    ├── Billing (Stripe subscriptions)
    └── Notifications (email, push)
```

## Integration Checklist

### 1. Product Identity (`shared/product.json`)

Ensure this file exists and is correct:
```json
{
  "productId": "<product_id>",
  "productName": "<ProductName>",
  "backendPort": <port>,
  "tokenNamespace": "--<prefix>-"
}
```

### 2. Backend Integration

#### Config (`backend/src/lib/config.ts`)
- Self-contained Zod schema (do NOT import zod from @bytelyst/config)
- Include: PORT, HOST, NODE_ENV, DB_PROVIDER, JWT_SECRET, PLATFORM_SERVICE_URL, CORS_ORIGIN

#### Auth (`backend/src/lib/auth.ts`)
- Re-export from `@bytelyst/fastify-auth`
- Wire auth hook in `server.ts` for protected routes

#### Datastore (`backend/src/lib/datastore.ts`)
- Re-export from `@bytelyst/datastore`
- Support `DB_PROVIDER=memory` for dev/test and `DB_PROVIDER=cosmos` for production

#### Product Config (`backend/src/lib/product-config.ts`)
- Read `shared/product.json`
- Export `PRODUCT_ID`, `PRODUCT_NAME`, etc.

#### Request Context (`backend/src/lib/request-context.ts`)
- `getUserId(req)` — extract userId from JWT
- `getRequestProductId(req)` — return productId from config

#### Feature Flags (`backend/src/lib/feature-flags.ts`)
- Initialize `@bytelyst/backend-flags` with product config
- Register product-specific flags

#### Telemetry (`backend/src/lib/telemetry.ts`)
- Initialize `@bytelyst/backend-telemetry`
- Buffer events for platform-service ingestion

#### Diagnostics (`backend/src/lib/register-diagnostics.ts`)
- Register `/api/diagnostics/flags`, `/api/diagnostics/events` routes
- Health endpoint at `GET /health`

### 3. Web Integration

#### Auth (`web/src/lib/auth.ts`)
```typescript
import { createAuthContext } from '@bytelyst/react-auth';
export const { AuthProvider, useAuth } = createAuthContext({
  platformUrl: process.env.NEXT_PUBLIC_PLATFORM_SERVICE_URL || 'http://localhost:4003',
  productId: '<product_id>',
});
```

#### API Client (`web/src/lib/api-helpers.ts`)
```typescript
import { createApiClient } from '@bytelyst/api-client';
export function createProductClient(getToken: () => string | null) {
  return createApiClient({
    baseUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:<port>',
    getToken,
  });
}
```

#### Design Tokens (`web/src/app/globals.css` or `client/src/index.css`)
- Import `@bytelyst/design-tokens` CSS
- Use product namespace: `--<prefix>-*` custom properties
- Never hardcode hex colors

#### Platform Clients
- `@bytelyst/feature-flag-client` — feature gating
- `@bytelyst/telemetry-client` — event tracking
- `@bytelyst/kill-switch-client` — remote kill switch
- `@bytelyst/diagnostics-client` — health monitoring

### 4. Mobile Integration (if applicable)

- `@bytelyst/auth-client` — login/register/token management
- `@bytelyst/telemetry-client` — event buffering
- `@bytelyst/feature-flag-client` — feature gating
- `@bytelyst/kill-switch-client` — remote disable
- `@bytelyst/offline-queue` — offline-first data sync

### 5. pnpm Workspace Configuration

`pnpm-workspace.yaml`:
```yaml
packages:
  - 'backend'
  - 'web'
  - 'mobile'
  - '../learning_ai_common_plat/packages/*'
```

`.npmrc` — sync from canonical template:
```bash
cd ../learning_ai_common_plat && bash scripts/sync-npmrc.sh
```

### 6. Docker Support

`docker-compose.yml`:
```yaml
services:
  backend:
    build: ./backend
    ports:
      - "<port>:<port>"
    env_file: ./backend/.env
    depends_on:
      - platform-service
```

### 7. Validation

```bash
# Backend
cd backend && pnpm install && pnpm typecheck && pnpm test && pnpm build

# Web
cd web && pnpm install && pnpm typecheck && pnpm build

# Verify auth flow
curl -X POST http://localhost:4003/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"test@example.com","password":"password"}'
# Use returned token against product backend:
curl http://localhost:<port>/health
curl http://localhost:<port>/api/<endpoint> \
  -H "Authorization: Bearer <token>"
```

### 8. Commit

```bash
git add .
git commit -m "feat(platform): wire @bytelyst/* ecosystem integration

- Auth: JWT via @bytelyst/fastify-auth + @bytelyst/react-auth
- Data: @bytelyst/datastore with memory/cosmos providers
- Flags: @bytelyst/feature-flag-client
- Telemetry: @bytelyst/telemetry-client
- Tokens: @bytelyst/design-tokens with --<prefix>-* namespace
- Tests: all passing"
git push
```