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

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

{
  "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)

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)

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:

packages:
  - 'backend'
  - 'web'
  - 'mobile'
  - '../learning_ai_common_plat/packages/*'

.npmrc — sync from canonical template:

cd ../learning_ai_common_plat && bash scripts/sync-npmrc.sh

6. Docker Support

docker-compose.yml:

services:
  backend:
    build: ./backend
    ports:
      - "<port>:<port>"
    env_file: ./backend/.env
    depends_on:
      - platform-service

7. Validation

# 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

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