# @bigscreen/cloud

The multiplayer / social brain. Owns room lifecycle, user presence, social graph, media-server registry, and the SQS queue abstraction used by every cloud-side process. Imported by `cloud/cloud_api`, `cloud/ws_server`, `cloud/cloud_worker`, and `cloud/media_server_next`.

**Path:** [cloud/](../../cloud) (workspace root).
**Source root:** [cloud/src/](../../cloud/src).
**Package name:** `@bigscreen/cloud`.
**Entry:** [cloud/index.ts](../../cloud/index.ts).

## Exports

```ts
export { Cloud } from "./src/Cloud";
export * as CloudAdminApi from "./src/CloudAdminApi";
export * as CloudApi from "./src/CloudApi";
export * as MediaServerApi from "./src/MediaServerApi";
export { MessageQueue, Queue, BigscreenCloudCommands, MediaServerCommands, CloudToWebsocketCommands } from "./src/MessageQueue";
export { RemoteQueue } from "./src/RemoteMessageQueue";
export * as CloudSchemas from "./src/Schemas";
export * as CloudDB from "./src/CloudDB";
```

## Module Boundaries

```mermaid
flowchart TB
    subgraph Core["Core state"]
        CLOUD["Cloud<br/>(rooms, users, media-servers)"]
        REDIS[("Redis")]
        DDB[("DynamoDB via CloudDB")]
    end

    subgraph API["HTTP handlers"]
        CAPI["CloudApi<br/>(public endpoints)"]
        CAA["CloudAdminApi<br/>(staff endpoints)"]
        MSA["MediaServerApi<br/>(media-server endpoints)"]
    end

    subgraph Queues["Queue transport"]
        MQ["MessageQueue<br/>(SQS wrapper)"]
        RQ["RemoteQueue<br/>(HTTP wrapper for<br/>non-AWS senders)"]
    end

    subgraph Domains["Domain sub-areas"]
        SOC["SocialAPI/<br/>friends, blocks,<br/>notifications"]
        ACT["Activities/<br/>browser sharing, games"]
    end

    SCHEMAS["Schemas<br/>(room, user, screen,<br/>notification types)"]
    ERR[Errors]

    CAPI --> CLOUD
    CAA --> CLOUD
    MSA --> CLOUD
    CAPI --> SOC
    CAPI --> ACT

    CLOUD --> REDIS
    CLOUD --> DDB

    CLOUD --> MQ
    MSA --> MQ
    MSA --> RQ

    CAPI --> SCHEMAS
    CAA --> SCHEMAS
    SOC --> SCHEMAS

    CAPI --> ERR
    SOC --> ERR
```

## Module Inventory

Every module lives at `cloud/src/<Name>.ts` unless noted.

| Module | Purpose |
|--------|---------|
| **Cloud** | The big one (~161 KB). Room creation/deletion, user admission, media-server registry, room data, seat assignment, integrity checks. The canonical mutation surface for everything in Redis. |
| **CloudApi** | Request handlers for the public `cloud_api` REST endpoints (rooms, social, screens, activities, channels, lobby, shared media, etc.). |
| **CloudAdminApi** | Request handlers for `/admin/*` on `cloud_api` (stats, room admin, user kick/eject). |
| **MediaServerApi** | Endpoints called by `media_server_next` (register, message, manifest). |
| **Schemas** | Types for rooms, users, screens, activities, notifications. Every cross-process message is an instance of one of these. |
| **MessageQueue** | SQS wrapper. Exports `Queue` enum (`BigscreenCloud`, `WebsocketInbox`, `WebsocketOutbox`) and command enums (`BigscreenCloudCommands`, `MediaServerCommands`, `CloudToWebsocketCommands`). |
| **RemoteMessageQueue** | HTTP-based queue transport used by media servers running outside AWS. |
| **CloudDB** | DynamoDB access (room history, some bookkeeping). |
| **CloudUtils** | Shared helpers (id generation, room name validation, etc.). |
| **Errors** | Custom error types used across the cloud library. |

## Sub-Domains

### `Activities/`

Shared-activity definitions — browser sharing, co-watching, games. Imported by `CloudApi` to back the `/activity/*` and `/apps/browser/*` endpoints.

Notable files:

- `Activities/SocialBrowserAPI.ts`
- `Activities/Schemas.ts`

### `SocialAPI/`

The social graph: friend lists, block lists, notifications (friend requests, room invites), presence, social history.

Notable files:

- `SocialAPI/SocialAPI.ts`
- `SocialAPI/SocialDB.ts` — Postgres access for social tables
- `SocialAPI/SocialDBSetup.ts` — schema setup
- `SocialAPI/SocialEmail.ts` — transactional emails (e.g. friend requests)
- `SocialAPI/Schemas.ts`

## Redis Keys Touched

The cloud library owns the shape of several Redis key families. Roughly:

| Key pattern | Purpose |
|-------------|---------|
| `mediaServers:<id>` | Media-server registry entry (region, heartbeat, capacity) |
| `mediaServer:rooms:<id>` | Set of room ids hosted on that media server |
| `room:<id>` | Room state (status, config, members, data key-value store) |
| `bigscreenUser:<id>` | Live user presence (session id, room, ws-server id) |
| `lock:room:<id>` | Redlock key for room-scoped mutations |
| `lock:user:<id>` | Redlock key for user-scoped mutations |
| `lock:mediaServer:<id>` | Redlock key for media-server updates |

Consult `Cloud.ts` for the authoritative list — this is a summary, not a contract.

## SQS Queues

| Queue | Senders | Receivers |
|-------|---------|-----------|
| `BigscreenCloud` | `cloud_api` (to media servers), `media_server_next` (to cloud), `ws_server` (to cloud) | `cloud_worker`, `cloud_api`'s in-process media-server worker, `media_server_next` (for cloud→ms commands) |
| `WebsocketInbox` | `ws_server` (user-sourced messages) | `cloud_worker` |
| `WebsocketOutbox` | `cloud_api`, `cloud_worker` | `ws_server` |

## Why this library is split from `api/`

Two reasons:

1. **Different DBs.** `@bigscreen/api` is Postgres-first. `@bigscreen/cloud` is Redis-first (with DynamoDB for history). Splitting keeps the heavier transient-state machinery out of the way of the account / order pipeline.
2. **Different clients.** `@bigscreen/api` endpoints are for web + admin. `@bigscreen/cloud` endpoints are for VR sessions and are sometimes called tens of times per second per user.

## Further reading

- Services that use this library → [services/cloud-api.md](../services/cloud-api.md), [services/ws-server.md](../services/ws-server.md), [services/cloud-worker.md](../services/cloud-worker.md), [services/media-server.md](../services/media-server.md)
- Room creation flow → [data-flows.md#2-room-creation](../data-flows.md#2-room-creation)
- Worker command reference → [services/cloud-worker.md](../services/cloud-worker.md)