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

```bash
# Build all packages
pnpm build

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

# Build all packages + services
pnpm build
```

### Quality Checks

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

# Full test suite
pnpm test

# Type-check all packages
pnpm typecheck
```

### Docker Preparation

```bash
# 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)