# Bigscreen Cloud Documentation

This is the documentation hub for the **Bigscreen Cloud** monorepo — the collection of server applications and web applications that power almost everything at Bigscreen: the VR app (Bigscreen Unity), the website, the Beyond face-scanning system, custom cushion production, Beyond shipping and inventory, and more.

For local dev setup, Redis/Postgres prerequisites, and build instructions see the repo-root [README.md](../README.md).

## System Map

```mermaid
flowchart LR
    %% Clients
    VR["VR Client<br/>(Bigscreen Unity)"]
    WEB["Website"]
    ARDA["Arda<br/>(React admin SPA)"]
    IOS["iOS Scan App"]
    FACTORY["Factory<br/>(CNC, Fusion 360)"]

    %% Public services
    API["apps/api<br/>(:3009)<br/>Auth + Media"]
    CLOUD["cloud/cloud_api<br/>(:3002)<br/>Multiplayer REST"]
    WS["cloud/ws_server<br/>(:3003)<br/>WebSockets"]
    MEDIA["cloud/media_server_next<br/>Mediasoup RTC"]

    %% Private services
    ADMIN["apps/admin_api<br/>(:3999)<br/>IP-restricted"]
    WORKER["cloud/cloud_worker<br/>Queue processor"]
    KB["apps/kb<br/>RAG service"]
    SCAN["apps/scan_yourself<br/>Face-scan backend"]

    %% Data stores
    PG[("PostgreSQL<br/>accounts, orders,<br/>analytics")]
    REDIS[("Redis<br/>rooms, locks,<br/>real-time state")]
    DDB[("DynamoDB<br/>cloud state")]
    SQS[["AWS SQS<br/>BigscreenCloud,<br/>WebsocketInbox/Outbox"]]
    VEC[("pgvector<br/>KB embeddings")]

    VR --> API
    VR --> CLOUD
    VR <--> WS
    VR <--> MEDIA

    WEB --> API
    WEB --> CLOUD
    IOS --> SCAN

    ARDA --> ADMIN
    ARDA --> CLOUD

    FACTORY --> ADMIN

    API --> PG
    API --> REDIS

    CLOUD --> REDIS
    CLOUD --> DDB
    CLOUD --> SQS
    CLOUD <--> MEDIA

    WS <--> SQS
    WORKER <--> SQS
    WORKER --> REDIS

    ADMIN --> PG
    ADMIN --> REDIS
    ADMIN --> KB

    KB --> VEC
    SCAN --> ADMIN
```

## Table of Contents

### Start here

- [architecture.md](./architecture.md) — full system architecture, ports, deployment model
- [workspaces.md](./workspaces.md) — yarn workspace reference + dependency graph
- [data-flows.md](./data-flows.md) — sequence diagrams for login, room creation, media heartbeat, etc.

### Running services

| Service | Path | Port | Purpose |
|---------|------|------|---------|
| [api](./services/api.md) | `apps/api/` | 3009 | Public authentication + media API |
| [admin-api](./services/admin-api.md) | `apps/admin_api/` | 3999 | Private admin API (IP-restricted) |
| [admin-api workers](./services/admin-api-workers.md) | `apps/admin_api/` | — | Background worker tasks (Big Order sync, shipper, KB sync) |
| [oauth](./services/oauth.md) | `apps/api/` + `apps/admin_api/` + `webapps/arda/` | — | OAuth 2.0 authorization server — token endpoint, client CRUD, consent UI |
| [shipping-configurations](./services/shipping-configurations.md) | `api/src/fabricator/` | — | Shipment group partitioning + box size selection (reference) |
| [cloud-api](./services/cloud-api.md) | `cloud/cloud_api/` | 3002 | Multiplayer REST API |
| [ws-server](./services/ws-server.md) | `cloud/ws_server/` | 3003 | WebSocket connection manager |
| [cloud-worker](./services/cloud-worker.md) | `cloud/cloud_worker/` | — | SQS/Redis message processor |
| [media-server](./services/media-server.md) | `cloud/media_server_next/` | RTC | Mediasoup-based media server |
| [monitor](./services/monitor.md) | `cloud/monitor/` | — | UDP performance monitor (Python) |
| [kb](./services/kb.md) | `apps/kb/` | — | Knowledge-base / RAG service |
| [scan-yourself](./services/scan-yourself.md) | `apps/scan_yourself/` | — | iOS face-scan backend |

### Shared libraries

| Library | Path | What it is |
|---------|------|------------|
| [@bigscreen/lib](./libraries/lib.md) | `lib/` | Logger, Redis, Postgres, utilities |
| [@bigscreen/auth](./libraries/auth.md) | `auth/` | JWTs, access policies, Steam/Oculus login |
| [@bigscreen/api](./libraries/api-handlers.md) | `api/` | Domain handlers shared by api + admin-api |
| [@bigscreen/cloud](./libraries/cloud-handlers.md) | `cloud/` | Rooms, social, media-server handlers |

### Web applications

- [arda](./webapps/arda.md) — React SPA for factory / admin / moderation staff

### Reference

- [external-services.md](./external-services.md) — AWS, databases, third-party APIs
- [testing.md](./testing.md) — test folders, how to run, survey runner

## Quick nav

- **New here?** Read [architecture.md](./architecture.md), then the service doc for whatever you're touching.
- **Writing an endpoint on `apps/api`?** See [services/api.md](./services/api.md) + [libraries/api-handlers.md](./libraries/api-handlers.md).
- **Working on OAuth / client credentials / scopes?** See [services/oauth.md](./services/oauth.md) for the surface, and the OAuth flow in [data-flows.md](./data-flows.md#7-oauth-authorization-code-flow-pkce).
- **Debugging multiplayer?** See [services/cloud-api.md](./services/cloud-api.md), [services/cloud-worker.md](./services/cloud-worker.md), [services/ws-server.md](./services/ws-server.md), and the relevant flow in [data-flows.md](./data-flows.md).
- **Factory / Shopify / shipping work?** See [services/admin-api.md](./services/admin-api.md) + the Fabricator section of [libraries/api-handlers.md](./libraries/api-handlers.md). For the full map of shipment groups and box sizes, see [services/shipping-configurations.md](./services/shipping-configurations.md).
- **Face-scanning?** See [services/scan-yourself.md](./services/scan-yourself.md) + the scan flow in [data-flows.md](./data-flows.md).

## Pre-existing design notes

Two design notes live alongside these docs and are not part of the rebuild:

- [cloud_worker_refactoring_proposal.md](./cloud_worker_refactoring_proposal.md)
- [debug_media_server_delay.md](./debug_media_server_delay.md)