The application is designed to run inside Docker containers. Do not run npm install or modify node_modules locally, as this can create environment drift. All development and building should be done through the provided Docker workflows.

Development

For live development with hot reloading, React DevTools support, and TypeScript compilation on-the-fly.

Prerequisites

Docker
Docker Compose

Running the Server (Backend)

The server uses TypeScript with hot reloading via ts-node-dev.

docker compose -f docker-compose.dev.yml up

This will:

Build the server container using Dockerfile.server
Mount the server/ directory for live code changes
Run npm run start:dev which uses ts-node-dev for hot reloading
Expose the server on port 8930

Testing the Server

The server uses Jest for unit testing. Tests are located in server/tests/.

To run tests:

docker compose run --rm server npm test

This will run all test files matching *.test.ts in the server/tests/ directory.

To run tests in watch mode:

docker compose run --rm server npm run test:watch

Note: If you add test:watch script, but for now, it's just test.

Running the Client (Frontend)

The client is a React application with hot reloading and debug support.

docker compose -f docker-compose.client.dev.yml up

This will:

Mount the client/ directory for live code changes
Run npm start in development mode
Enable React DevTools and hot module replacement
Expose the client on port 3001 (HTTPS)
Proxy API calls to the server at http://host.docker.internal:8930

Full Development Stack

To run both server and client together:

# Terminal 1: Server
docker compose -f docker-compose.dev.yml up

# Terminal 2: Client
docker compose -f docker-compose.client.dev.yml up

Open https://localhost:3001 in your browser. The client will hot-reload on code changes, and the server will restart automatically on backend changes.

Production

For production deployment, the client is built as static files and served directly by the Node.js server.

Building

docker compose build

This builds the production image using Dockerfile, which:

Installs server dependencies and builds TypeScript to dist/
Installs client dependencies and builds static files to client/build/
Copies the built client files to be served by the server

Running

docker compose up

This will:

Start the server on port 8930
Serve the built client static files
Mount the db/ directory for persistent database storage
Mount server/routes/ for dynamic route files

The application will be available at http://localhost:8930.

Environment Variables

Create a .env file in the project root with any required environment variables. The server start script loads these via export $(cat ../.env | xargs).

Architecture

skinparam componentStyle rectangle

component "Server" as server
component "Resources" as res
component "Client" as client
component "Game" as game
component "Player" as player

package "Game" as game {
  component Players as players
}

server <-> resource : serves static files to client
client <-> server : API calls
player <-> client
players -r-> player
server -> game

API Documentation

POST /api/v1/game

Request

{}

Response

{
  "gameId": "id",
  "gameState": {
    "tiles": []
  }
}

Configuration

Add security tokens in server/config/local.json:

cat << EOF > server/config/local.json
{
  "tokens": [ {
    "$(whoami)": "$(< /dev/urandom tr -dc _A-Z-a-z-0-9 | head -c${1:-32};echo;)"
  } ]
}
EOF

Testing

Create New Game

curl -X POST http://localhost:8930/api/v1/games/

Get Game Status

curl -X GET http://localhost:8930/api/v1/games/:id

Game States

Lobby: Players register, choose colors, roll for position, set ready
Active: Gameplay phase

Chat is available at all times for registered players.

License Attribution

The dice faces (dice-six-faces-*.svg) are Copyright https://delapouite.com/ and licensed as CC-BY-3.0.

Languages

TypeScript 86.5%

JavaScript 5.8%

CSS 5.7%

Shell 0.9%

Dockerfile 0.6%

Other 0.5%