# Bigscreen Cloud

This is a monorepo for Bigscreen "cloud".  The cloud is a collection of server applications and web applications.  These apps support almost everything at Bigscreen, including the Bigscreen Unity app, the Bigscreen website, the Beyond face scanning system, custom cushion production, Beyond shipping and inventory, and so on.

The monorepo is split into several main sections:

0. `api` - Source code for each api.
1. `apps` - api servers used across the entire organization
  * `apps/api/api.ts` - the publicly available auth server.  All applications use this server to authenticate users.
  * `apps/admin_api/admin_api.ts` - a private admin api server.  This is primarily used by the `arda` web application.  In production, the "admin_api" application runs on an EC2 server with a security group that only allows valid IP addresses.
  * `apps/admin_api/db_setup.ts` - a script for setting up the postgres database.
  * `apps/admin_api/scan_yourself.ts` - an app for supporting the iOS face scanning app, and a set of AWS lambda functions the support this feature.
3. `auth` - Libraries to handle application keys and access token auth.
4. `cloud` - contains applications and servers that support the Bigscreen VR app:
   * `cloud/cloud_api/cloud_api.ts` - a publicly available web server with apis for real time information about people using the bigscreen app.  Used for multiplayer features on the Bigscreen app.
   * `cloud/cloud_api/cloud_setup` - sets up cloud databases on AWS Dynamo DB and Postgres.
   * `cloud/cloud_api/cloud_worker` - a worker application that runs several multiplayer functions.
   * `cloud/cloud_api/media_server_aws` - a media server (forwards video/audio/movement data) that is designed to run specifically on AWS.
   * `cloud/cloud_api/media_server_next` - a media server designed to run anywhere, tested on Digital Ocean and AWS so far.
   * `cloud/cloud_api/monitor` - media server monitoring tool.
   * `cloud/cloud_api/ws_server` - the cloud web socket server
5. `docs` - where docs should go.
6. `lib` - general purpose libraries used by each application.
7. `tests` - integration tests for each api. See the section in README.md in [Running Tests](#running-tests) for more.
    * `api` - general api tests
    * `auth` - test account creation and auth.
    * `cloud-api` - tests for the features of the `cloud-api` server.
    * `fabricator` - apis used specifically by arda, and various stations in the LA factory.
    * `scan-yourself` - tests for the face scanning app.
    * `social` - all tests for the social friends system in the Bigscreen app.
8. `webapps` - Just the one webapp now:
    * Contains the `arda` web application [See the README in root of the webapps folder for more](/webapps).

## Coding Conventions
- Use `yarn` for all package.json related changes. This monorepo does NOT use `npm`.
- API responses follow REST conventions.
- Use typescript unless otherwise specified.
- Use yarn with node_modules for package management etc.
- The repo contains yarn workspaces for each different app, around 15 in total.
  - IMPORTANT: a build step should only use workspace build commands.  Do NOT cd to the directory and `yarn build` because it will create build output in the wrong place.
- All integration tests are in the `tests` folder. Tests should be run with `ts-mocha` from the `tests` folder.  Here is an example:
```
ts-mocha --bail --exit --timeout=500000 api/098.RateLimiter.ts
```

## 🚨 CRITICAL: ALWAYS USE ABSOLUTE PATHS 🚨

**NEVER use `cd ..` or `cd ../..` - there have been devastating mistakes due to directory confusion.**

**ALWAYS:**

1. Run `pwd` first to check your current directory
2. Use absolute paths: `cd /home/cloud` or `cd /home/cloud/src/api/whatever`
3. When in doubt, ask the user to confirm the intended directory

## 🚨 CRITICAL: NEVER READ .env FILES 🚨

These files can not be read by claude code.

## IMPORTANT: Don't use tabs, use 4 spaces per indent rather than 2.

For example

```
if (foo) {
    if (bar) {
        hello();
    }
}
```

## IMPORTANT: Only build with workspace commands defined in the root `package.json`

Do not build with tsc directly to test if builds are correct.  Instead, build with the relevant workspace command, defined in the root package.json.

Generally, prefer `ts-node` to run programs, which doubly works as a build verifier (for this most part).

This is because a tsc will leave built artifacts in non ignored locations.

## Security Context:

1. For APIs servers, all endpoints require an "Authorization" header with a valid key.
2. In addition to this, outside of "/auth" endpoints on the auth server, all HTTP endpoints require a valid access token to use.
3. IMPORTANT: All .env files should be IGNORED.  DO NOT READ THEM.


## Webpack:

Expect `yarn dev` to be running in a separate tab.  This spins up nodemon instances for every single application and process, and builds any changes.

In particular, it is NOT NECESSARY to run webpack after a change on any application in the `webapps` folder.

## Ignore .archive folders

A few apps have a .archive folder with older code - the contents of these folders should be ignored.