# CLAUDE.md — orchard-suite

This file provides guidance for AI assistants working in the orchard-suite repository.

## Project Overview

**orchard-suite** is a pnpm monorepo containing 71 shared packages for the Orchard Insights platform. It produces reusable React components, build tools, GraphQL utilities, connectors, and configuration packages consumed by `frontend-insights` and other Orchard applications. Published to GitHub Packages under the `@theorchard` scope.

## Essential Commands

```bash
# Install dependencies (pnpm enforced — npm/yarn will fail)
pnpm install

# Run all tests
pnpm test

# Run tests for a specific package
pnpm -F @theorchard/suite-components test:unit
pnpm -F @theorchard/suite-frontend test:unit

# Build a specific package
pnpm -F @theorchard/suite-components build
pnpm -F @theorchard/suite-icons build

# Lint
pnpm -F @theorchard/suite-components lint
pnpm -F @theorchard/suite-components lint:js
pnpm -F @theorchard/suite-components lint:css

# Format
pnpm -F @theorchard/suite-components format

# Run the Solfege app (component showcase)
pnpm -F frontend-solfege dev          # Vite dev server
pnpm -F frontend-solfege frontend build  # Webpack build
```

## Setup

- **Node.js**: >=24.11
- **pnpm**: 9.0.5 (enforced via preinstall hook — do NOT use npm or yarn)
- **NPM Registry**: GitHub Packages (`@theorchard` scope) — requires `GITHUB_NPM_TOKEN`

## Architecture

### Tech Stack

| Layer | Technology |
|-------|-----------|
| Monorepo | pnpm 9.0.5 workspaces |
| UI Framework | React 18 |
| Language | TypeScript 5.6.2 (strict mode) |
| Build (packages) | tsc (ESM + CJS dual output) |
| Build (apps) | Vite 7.3 (+ Webpack legacy) |
| Testing | Vitest 4.0.15 (primary), Jest 29 (legacy) |
| Testing Library | @testing-library/react 16.1 |
| Styling | SCSS + @theorchard/suite-theming |
| Formatting | Prettier 3.2.5 |
| Linting | ESLint (multiple configs per package type) |

### Workspace Structure

```
orchard-suite/
├── packages/                    # 70+ reusable packages
│   ├── suite-components/        # 70+ React UI components (MAIN PACKAGE)
│   ├── suite-frontend/          # Frontend utilities, hooks, styles
│   ├── suite-icons/             # Icon library + SVG assets
│   ├── suite-apollo/            # Apollo Client provider & helpers
│   ├── suite-auth/              # Auth0 integration
│   ├── suite-config/            # Configuration management
│   ├── suite-identity/          # User identity / feature flags
│   ├── suite-theming/           # Theme management
│   ├── suite-testing/           # Shared testing utilities
│   ├── suite-utils/             # General utilities
│   ├── frontend-cli/            # Build CLI (Webpack/Vite subcommands)
│   ├── frontend-cli-vite/       # Vite integration
│   ├── frontend-cli-webpack/    # Webpack integration (legacy)
│   ├── graphql-server/          # Apollo Server wrapper
│   ├── graphql-integration/     # GraphQL test utilities
│   ├── graphql-codegen-config-frontend/ # Codegen presets
│   ├── connector-neo4j/         # Neo4j driver wrapper
│   ├── connector-splitio/       # Split.io client
│   ├── connector-spotify/       # Spotify API client
│   ├── datasource-neo4j/        # Neo4j DataSource
│   ├── datasource-ows/          # OWS REST DataSource
│   ├── datasource-kafka/        # Kafka DataSource
│   ├── dataloader-zod/          # Zod-validated DataLoader
│   ├── dataloader-redis-zod/    # Redis-backed DataLoader
│   ├── constants/               # Shared constants
│   ├── countries/               # Country data utilities
│   ├── field-validator/         # Schema validation
│   ├── generator-graphql-server/# Scaffolder for GraphQL services
│   ├── generator-suite-app/     # Scaffolder for frontend apps
│   └── ... (40+ more)
├── apps/                        # Applications
│   └── frontend-solfege/        # Component showcase / living docs
├── archive/                     # Deprecated packages
├── pnpm-workspace.yaml          # Workspace definition
├── tsconfig.suite.json          # Root TypeScript config with project refs
├── vitest.config.ts             # Root Vitest config
└── package.json                 # Root package.json
```

### Package Build Output

Each package produces dual output:
- **ESM**: `dist/esm/src/index.js` (modern browsers, Node.js ESM)
- **CJS**: `dist/cjs/src/index.js` (Node.js CommonJS, legacy)
- **Types**: `dist/esm/src/index.d.ts`

Packages use conditional exports in `package.json` with subpaths (`.`, `./styles`, `./vars`).

## Key Packages

### suite-components (Main)

70+ React UI components. Has its own `CLAUDE.md` and `AGENTS.md` with detailed component development patterns. **Read those files first when working on components.**

Key conventions:
- Uppercase `CLASSNAME` constant
- `classnames` as `cx`
- Always include `testId` prop
- JSDoc with `@type`, `@status`, `@tags`
- Sub-components in `components/` folder

### suite-frontend

Frontend utilities consumed by all Orchard apps:
- Custom hooks (`useIdentity`, `useBrand`, etc.)
- Styles and SCSS variables
- App initialization plugins
- i18n support

### graphql-server

Shared Apollo Server wrapper used by all graphql-* backend services. Provides standardized configuration, middleware, and error handling.

### datasource-ows

REST DataSource for connecting to OWS Python services. Used by all graphql-* services that call OWS endpoints.

### dataloader-zod / dataloader-redis-zod

Zod-validated DataLoader factories. Standard pattern across all graphql-* services for batching and caching.

## Development Guidelines

### Adding a New Package

1. Create directory in `packages/<name>/`
2. Add `package.json` with `@theorchard/<name>` scope
3. Add `tsconfig.esm.json` + `tsconfig.cjs.json`
4. Add to `tsconfig.suite.json` references
5. Add build scripts
6. pnpm will auto-detect via workspace config

### Modifying Shared Packages

Changes to packages like `suite-components` or `graphql-server` affect all downstream consumers. Always:
1. Check for breaking changes
2. Run tests in the package
3. Consider version bumping strategy (patch/minor/major)
4. Test in consuming apps when possible

### Build Order

Some packages have build dependencies. The Jenkins pipeline builds in order:
1. `field-validator`, `frontend-cli-vite`, `frontend-cli`
2. `suite-icons` (ESM)
3. `suite-frontend` (ESM)
4. `suite-components` (ESM)
5. `suite-testing` (ESM)
6. Applications (frontend-solfege)

## pnpm Configuration

- `hoist=false` — strict dependency isolation
- `strict-peer-dependencies=false` — lenient peer deps
- `auto-install-peers=true` — auto-install peer deps
- `packageExtensions` — custom peer deps for react-idle-timer, bootstrap

## CI/CD (Jenkins)

1. Install pnpm via corepack
2. `pnpm install --frozen-lockfile`
3. Build packages in dependency order
4. Sync translations (suite-components, suite-frontend)
5. Build frontend-solfege (generate docs, usage, manifest)
6. Deploy to CDN (QA/Prod)