Guess BTC next move!

Screenshots

Mobile

Desktop

Architecture overview

A web app where users guess if Bitcoin's price will go higher or lower after one minute, with real-time updates and score tracking, backed by AWS.

The user is interacting with React frontend that sends and receives data via REST API provided by NestJS backend. The backend communicates with the Binance API to retrieve real-time Bitcoin price data and with AWS DynamoDB to store and manage game-related data, such as guesses and scores.

Folder structure

.
├── .github/      Deploy action
├── assets/       Images for README
├── client/       React frontned
└── server/       Nest backend

Prerequisites

Needed tools

• Node: v20.14.0 (recommended)
• NPM: 10.9.0 (recommended)
• Playwright (run npx playwright install)

Run Locally

Clone the project

git clone https://github.com/zaikinv/crypto-guesser.git

Go to the project directory

cd crypto-guesser

Install dependencies

cd client && npm i && cd ../server && npm i && cd ..

🚨 Set up AWS as described in the AWS Setup section.

Start client & server

cd client && npm run start & cd ../server && npm run start

...wait for client & server to startup, then open http://localhost:5173/ (or URL indicated in your terminal in case port 5173 is in use) in your browser.

🚨 Depending on your local port availability, you may need to adjust the apiBaseUrl in the client/src/config.ts file. See Configuration section for more details.

AWS Setup

Option 1

Set environment variables in server/.envfile:

AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_REGION=eu-central-1
API_KEY=

where API_KEY is a secret key that will be used to authenticate requests to the backend. You can leave it empty while running locally.

🚨 Please reach out to me if you would like me to setup an AWS account for you.

Option 2

Setup the following in DynamoDB:

• Users table with userId as the primary key
• Guesses table with guessId as the primary key
• UserIdIndex index on Guesses table with userId as the partition key and timestamp as the sort key.
• IAM user with AmazonDynamoDBFullAccess policy attached

API Documentation (Swagger)

https://d32hsgqukl039n.cloudfront.net/api-docs

or http://localhost:5173/api-docs if running locally.

Sequence diagrams

Login

Submit and validate guess

Configuration

Frontend

See the client/src/config.ts file for the application configuration.

const appConfig = {
  apiBaseUrl: 'http://localhost:8080/api',
  priceChangeTimeout: 30000,
  guessTimeout: 60,
  currency: 'USD',
}

Backend

See the server/src/config.ts file for the application configuration.

const appConfig = {
  priceApiBaseUrl: 'https://api.binance.com/api/v3',
  guessTimeout: 60,
  symbol: 'BTCUSDT',
}

Deployment

Deploy on AWS

The GitHub Action has to be manually triggered. The pipeline is installing dependencies, building the codeand running the tests. Once the build process is complete, the pipeline deploys both the React frontend and NestJS backend as containerized applications into an Elastic Beanstalk environment.

Unit Tests

Unit

Frontend

cd client && npm run test:unit

Backend

cd server && npm run test:unit

E2E

Frontend

🚨 Make sure the backend is running before running E2E tests and if not, run cd server && npm run start first.

cd client && npm run test:e2e

You can also run E2E tests in Playwright UI by running cd client && npm run test:e2e-ui.

Backend

cd server && npm run test:e2e

Known limitations

• After 60 seconds the price might not change, which will result in a draw (logic in this case: the guess can be either UP or DOWN, but in this case it is neither UP nor DOWN)
• When user submits a guess, the price that is visible is submitted to ensure fairness, the actual price at the exact moment may differ
• Unit and E2E tests are not covering all the codebase, but only the most critical parts
• E2E tests are intentionally excluded from the pipeline due to the time & resources constraints and still can be run locally
• Nest build doesn't work well within npm workspace and requires an own standalone package unless Nest custom monorepo is used