learning_ai_common_plat/REPO_CONTEXT.md

ByteLyst Common Platform - Repository Context

Purpose: This file provides quick context for AI coding agents about what this repository contains and how to use it effectively.

What This Repository Provides

This is the shared platform repository for the ByteLyst ecosystem. It contains:

• 36 shared libraries (@bytelyst/* packages) used across all products
• Platform services (platform-service, extraction-service, mcp-server)
• Internal dashboards (admin-web, tracker-web, ux-lab)
• MCP/A2A tooling and orchestration infrastructure
• Design tokens and cross-platform SDKs

Key Locations

Packages (Shared Libraries)

• Location: packages/
• Pattern: All packages are scoped as @bytelyst/{package-name}
• Count: 36 packages covering auth, config, storage, telemetry, diagnostics, etc.
• Build: Individual packages via pnpm --filter @bytelyst/{package} build
• Key Packages:
  • @bytelyst/config - Environment configuration and product identity
  • @bytelyst/cosmos - Azure Cosmos DB client singleton
  • @bytelyst/auth - JWT utilities and auth middleware
  • @bytelyst/api-client - Configurable fetch wrapper with auth
  • @bytelyst/telemetry-client - Client diagnostics and event batching
  • @bytelyst/llm - LLM client utilities
  • @bytelyst/devops - Build metadata and deployment utilities

Services

• Location: services/
• platform-service: Product-agnostic platform API (port 4003)
• extraction-service: LangExtract text extraction + Python sidecar (port 4005)
• mcp-server: MCP tool server + A2A orchestration

Scripts

• Location: scripts/
• docker-prep.sh: Build all packages before Docker builds
• quick-check.sh: Quick quality check (5 min) - run before pushing
• sync-npmrc.sh: Sync .npmrc template to all product repos
• prototype-self-test.sh: Prototype health check script

Documentation

• Location: docs/
• ecosystem/: Cross-product strategy and shared-contract documentation
• devops/gitea-runner/: Canonical Hostinger Gitea Actions runner rollout docs and delegation prompt
• PROTOTYPE_DEPLOYMENT.md: Prototype deployment guide

Common Usage Patterns

Building Packages

# Build all packages
pnpm build

# Build specific package
pnpm --filter @bytelyst/config build

# Build all packages + services
pnpm build

Quality Checks

# Quick check (before pushing)
./quick-check.sh

# Full test suite
pnpm test

# Type-check all packages
pnpm typecheck

Docker Preparation

# Build all packages before Docker builds (critical!)
./scripts/docker-prep.sh

Package Dependencies

Workspace Protocol

• Uses pnpm workspace with workspace:* protocol
• Dependencies between packages use: "@bytelyst/config": "workspace:*"
• External dependencies use standard semver ranges

Build Order

• Always build common-plat packages before product repos
• Docker builds depend on packages being pre-built via docker-prep.sh
• Product repos import from learning_ai_common_plat/packages/{package}/dist/

Package Scope Rules

• @bytelyst/* = shared libraries (packages/)
• @lysnrai/* = platform services (services/)
• Products consume @bytelyst/* packages

Integration with Product Repos

When Working in Product Repos

1. If you need to modify a shared package, do it here first
2. Build the package: pnpm --filter @bytelyst/{package} build
3. Then rebuild the product that consumes it
4. For Docker builds in products, always run ./scripts/docker-prep.sh first

Common Issues

• "Cannot find module @bytelyst/...": Package needs to be built
• Docker build fails: Run docker-prep.sh to build all packages first
• Version conflicts: Check workspace protocol in package.json files

NPM Registry Configuration

Gitea Registry

• Registry: http://localhost:3300/api/packages/bytelyst/npm/
• Token: Managed via .npmrc template
• Template: scripts/npmrc.template
• Sync Script: scripts/sync-npmrc.sh (syncs to all product repos)

.npmrc Management

• NEVER edit .npmrc files directly in product repos
• Use the canonical template in this repo
• Sync changes to all repos via sync-npmrc.sh

TypeScript Configuration

Base Configuration

• File: tsconfig.base.json
• Target: ES2022, NodeNext module resolution
• Strict mode: Enabled
• All packages/services extend this base config

Testing

Test Runner

• Framework: Vitest
• Command: pnpm test (runs all package tests)
• Pass with no tests: Configured at root level
• Individual packages: pnpm --filter @bytelyst/{package} test

Important Notes

Before Making Changes

1. Read the specific package's documentation
2. Check if changes affect consuming products
3. Run quick-check.sh before committing
4. Consider impact on all ecosystem products

Package Publishing

• Packages are published to internal Gitea registry
• Not published to public npm registry
• Version management follows semantic versioning

Design Tokens

• Canonical source: packages/design-tokens/tokens/bytelyst.tokens.json
• Generator: packages/design-tokens/scripts/generate.ts
• Outputs: CSS, TypeScript, Kotlin, Swift, React Native
• NEVER hardcode colors - always use design tokens

Quick Reference for Common Tasks

Task	Command
Build all packages	pnpm build
Build specific package	pnpm --filter @bytelyst/{package} build
Quick quality check	./quick-check.sh
Prepare for Docker builds	./scripts/docker-prep.sh
Run tests	pnpm test
Type-check	pnpm typecheck
Sync .npmrc to all repos	./scripts/sync-npmrc.sh

Related Repositories

• bytelyst-devops-tools: Deployment scripts and operational automation
• Product repos: learning_ai_invt_trdg, learning_ai_notes, etc. (consume these packages)