Rusty Reflexes

A fullstack Rust application which allows users to buzz-in in a Jeopardy-style game.

Introduction

This is a fullstack webapp which replaces the need for physical buzzers when playing group games in which only one player should be able to respond first.

The app serves a user who starts the game ("Host") and several users who join the game ("Players"). Here is a sample workflow:

1. The Host creates a new lobby and is given a game code
2. The Players join the lobby using the game code and supplying a name
3. The Host clicks a button to open the round
4. Players can click the button when they are ready
5. The first Player to click the button is noted on their screen and the Host's screen
6. The Host can then press the reset button and then open the next round

Some benefits of our solution:

• Allows a variable number of users to connect
• Removes the clutter of cables from traditional buzzers
• Makes it simple for anyone with an internet-capable device to join

Installation/running

Dependencies

This app requires Docker installed to function. See this guide for instructions to install Docker.

The remaining dependencies are installed within a Docker container for portability and simplified installation.

Installing

1. Clone this repository
2. Run docker compose up --build from the root of the project

This will build the Docker image and start the app.

Running

To run the app, run docker compose up. This will build the frontend, start the database, and run the backend.

You can run docker compose up -d to run in the background, stopping it with docker compose down.

After this, the server will be exposed at http://localhost:2220/.

Updating

1. Load the latest changes (perhaps by a git pull)

2. Run docker compose down to shut down the server (if not already stopped)

3. Run docker compose up --build to rebuild the backend

Technical Architecture

Frontend

The frontend code is in frontend/.

This code includes all WebAssembly code, written in Yew. Yew is our selected Rust frontend framework.

The frontend code is build using trunk. Docker then passes this built (.wasm) code to the backend (using a Docker volume link).

Backend

The backend code is in backend/.

This code includes the backend Rust code, using the Rust server framework Actix.

The backend serves both the static (pre-generated) frontend code as well as different API endpoints on its server.

The API endpoints include routes such as joining a room. The backend server also exposes a WebSocket connection for fast connections during the game.

Database

PostgreSQL is used as the database.

Development note

The library used for PostgreSQL, sqlx, requires one of the following during build time:

1. A live connection to the database
2. Cached .sqlx queries

A live connection to the database is not easily achieved during build time due to Docker service constraints.

To get these cached files generated, cargo sqlx prepare must be ran whenever a SQL query is added or modified in the backend. (Otherwise, the build will fail.)

The database must be ran when cargo sqlx prepare is ran. You can start the database service and then run this command.

.sqlx files should then be committed to Git for this to work on other machines.

Docker

Docker compose is used for this project. This runs multiple services independently.

The backend server runs on 0.0.0.0:8080. Docker routes requests to port 2220 on the local machine to this address.

Other services are visible by their name in the compose file. Hence, the backend uses the host db to connect to the database (not the exposed localhost:2221).

The database is also exposed at localhost:2221 for ad-hoc queries (authentication is required).

Group members & roles

• Elijah (ekcom): Docker administrator, design/mockup creator
• Sebastian (SebWysz): Frontend developer, websocket engineer
• Jun (7unlim): Backend developer, service integrator
• Aaron (aaronjiang25): Database administrator, test engineer

Development

Running

To develop the app, run docker compose up --build to start the server.

Any changes to frontend/ should be rebuild immediately, and refreshing the page will show the changes.

Upon changing the backend/ files, you will need to Ctrl+C to kill the server and docker compose up --build to rebuild it.

Testing

Integration tests

Run this to run the integrations tests, written in Playwright for Rust:

docker compose --profile test up