# Yarn Workspaces

The monorepo uses Yarn 3 workspaces. The authoritative list lives in the root [`package.json`](../package.json) under the `workspaces` field. Yarn resolves cross-workspace dependencies through `workspace:^` protocol entries in each package.json.

**Always use `yarn`, never `npm`.** The repo root CLAUDE.md is firm on this, and `packageManager: "yarn@3.2.3"` is pinned.

## Dependency Graph

```mermaid
flowchart BT
    LIB["@bigscreen/lib<br/>lib/"]
    AUTH["@bigscreen/auth<br/>auth/"]
    API_LIB["@bigscreen/api<br/>api/"]
    CLOUD_LIB["@bigscreen/cloud<br/>cloud/"]

    APPS_API["bigscreen_api<br/>apps/api/"]
    APPS_ADMIN["bigscreen_admin_api<br/>apps/admin_api/"]
    APPS_KB["apps/kb/"]

    CLOUD_API["bigscreen_cloud_api<br/>cloud/cloud_api/"]
    CLOUD_WS["bigscreen_ws_server<br/>cloud/ws_server/"]
    CLOUD_WORKER["cloud/cloud_worker/"]
    CLOUD_MEDIA["cloud/media_server_next/"]
    CLOUD_SETUP["cloud/cloud_setup/"]

    TESTS["tests/"]

    AUTH --> LIB
    API_LIB --> LIB
    API_LIB --> AUTH
    CLOUD_LIB --> LIB
    CLOUD_LIB --> AUTH
    CLOUD_LIB --> API_LIB

    APPS_API --> LIB
    APPS_API --> AUTH
    APPS_API --> API_LIB

    APPS_ADMIN --> LIB
    APPS_ADMIN --> AUTH
    APPS_ADMIN --> API_LIB

    APPS_KB --> LIB
    APPS_KB --> AUTH

    CLOUD_API --> LIB
    CLOUD_API --> AUTH
    CLOUD_API --> API_LIB
    CLOUD_API --> CLOUD_LIB

    CLOUD_WS --> LIB
    CLOUD_WS --> AUTH
    CLOUD_WS --> CLOUD_LIB

    CLOUD_WORKER --> LIB
    CLOUD_WORKER --> CLOUD_LIB

    CLOUD_MEDIA --> LIB
    CLOUD_MEDIA --> CLOUD_LIB

    CLOUD_SETUP --> LIB
    CLOUD_SETUP --> CLOUD_LIB

    TESTS --> LIB
    TESTS --> AUTH
    TESTS --> API_LIB
    TESTS --> CLOUD_LIB
```

Libraries at the bottom, services on top. Arrows point **toward** dependencies (readable as "is-built-on").

## Workspace Reference

| Workspace path | Package name | Kind | Docs |
|----------------|-------------|------|------|
| `lib` | `@bigscreen/lib` | Library | [libraries/lib.md](./libraries/lib.md) |
| `auth` | `@bigscreen/auth` | Library | [libraries/auth.md](./libraries/auth.md) |
| `api` | `@bigscreen/api` | Library | [libraries/api-handlers.md](./libraries/api-handlers.md) |
| `apps/api` | `bigscreen_api` | Service | [services/api.md](./services/api.md) |
| `apps/admin_api` | `bigscreen_admin_api` | Service | [services/admin-api.md](./services/admin-api.md) |
| `apps/kb` | `bigscreen_kb` | Service | [services/kb.md](./services/kb.md) |
| `cloud` | `@bigscreen/cloud` | Library | [libraries/cloud-handlers.md](./libraries/cloud-handlers.md) |
| `cloud/cloud_api` | `bigscreen_cloud_api` | Service | [services/cloud-api.md](./services/cloud-api.md) |
| `cloud/cloud_setup` | `bigscreen_cloud_setup` | Setup scripts | See below |
| `cloud/cloud_worker` | `bigscreen_cloud_worker` | Service (worker) | [services/cloud-worker.md](./services/cloud-worker.md) |
| `cloud/media_server_next` | `bigscreen_media_server_next` | Service (media) | [services/media-server.md](./services/media-server.md) |
| `cloud/ws_server` | `bigscreen_ws_server` | Service (websocket) | [services/ws-server.md](./services/ws-server.md) |
| `tests` | `bigscreen_tests` | Integration tests | [testing.md](./testing.md) |

## Non-Workspace Packages

These exist in the tree but are not declared as yarn workspaces. They're standalone packages or subprojects with their own `package.json` / `node_modules`:

| Path | What it is |
|------|------------|
| [`webapps/arda/`](../webapps/arda) | Arda — React admin SPA (Webpack 4). See [webapps/arda.md](./webapps/arda.md). |
| [`webapps/src/`](../webapps/src) | Shared React components imported by arda. |
| [`website/`](../website) | Minimal client-side bundle for the Bigscreen website (a companion build, not a full webapp in this repo). |
| [`apps/scan_yourself/`](../apps/scan_yourself) | iOS face-scan backend + AWS Lambda helpers. See [services/scan-yourself.md](./services/scan-yourself.md). |
| [`apps/db_setup/`](../apps/db_setup) | Database setup scripts (referenced from CLAUDE.md as `apps/admin_api/db_setup.ts`; the repo has evolved and it now lives under `apps/db_setup`). |
| [`cloud/media_server_aws/`](../cloud/media_server_aws) | Legacy AWS-specific media server (predecessor to `media_server_next`). Kept for historical comparison and limited production use. |
| [`cloud/monitor/`](../cloud/monitor) | Media-server monitoring tool. See [services/monitor.md](./services/monitor.md). |
| [`cloud/activities/`](../cloud/activities) | Shared-activity definitions (browser sharing, co-watching). Imported by cloud handlers. |
| [`clients/python/`](../clients/python) | Python SDK for external scripts / integrations. See [`clients/python/admin-api.md`](../clients/python/admin-api.md). |
| [`jenkins/`](../jenkins) | Reserved for CI config. Currently empty. |

## Root Scripts

Repo-root [`package.json`](../package.json) provides convenience scripts that avoid needing to `cd` into each workspace. **Always use the workspace-aware versions; never `cd <workspace> && yarn build` because it puts build output in the wrong place** (see CLAUDE.md).

| Script | Runs |
|--------|------|
| `yarn build` | `tsc --build` with 8 GB max heap — builds every TS workspace |
| `yarn dev` | `concurrently` launches admin-api, api, cloud-api, ws-server, arda-server, arda-webpack under their nodemon configs |
| `yarn dev:api` | Just apps/api under nodemon |
| `yarn dev:admin-api` | Just apps/admin_api |
| `yarn dev:cloud-api` | Just cloud/cloud_api |
| `yarn dev:ws-server` | Just cloud/ws_server |
| `yarn dev:arda-server` | Just arda's node server |
| `yarn dev:arda-webpack` | Arda's webpack --watch |
| `yarn start:api` / `start:admin-api` / `start:cloud-api` / `start:ws-server` / `start:arda` | One-shot starts (no nodemon) |
| `yarn webpack:arda` | One-shot arda bundle (non-watch) |
| `yarn test:survey` | Run the [survey test runner](./testing.md) over changed tests |
| `yarn test:survey:full` | Run every test in the survey |
| `yarn test:parallel` | Parallel survey runner |
| `yarn test:review` | Review tool for survey results |

## Installation Order

`yarn install` at the repo root wires up all workspaces in one go. Per CLAUDE.md and the repo root README, some legacy install commands target individual workspaces (`yarn workspace @bigscreen/lib install`, etc.) — these are usually unnecessary after a clean `yarn install` at root.

One important exception: `cd webapps && yarn install` is still needed, because `webapps/` is not a yarn workspace of the root. The root `install-dev-deps` script takes care of both: `yarn install && cd webapps && yarn install`.