Peddlers of Ketran

This project consists of both the front-end React client and back-end Node.js game API server for the Settlers of Catan-style board game.

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 and Production

The application can be launched in development or production mode by setting the PRODUCTION environment variable.

• Set PRODUCTION=0 (or leave unset) for development mode: hot-reloading server and client.
• Set PRODUCTION=1 for production mode: static built site served by the server.

Prerequisites

• Docker
• Docker Compose

Launching

# For development (hot-reload)
PRODUCTION=0 ./launch.sh

# For production (static build)
PRODUCTION=1 ./launch.sh

Development Mode

When PRODUCTION=0:

• Server runs with hot-reloading via ts-node-dev on port 8930
• Client runs with React hot module replacement on port 3001 (HTTPS)
• Client proxies API calls to the server
• Both services run in separate containers with mounted source directories

Open https://localhost:3001 in your browser for the client. Changes to server or client code will trigger automatic reloads.

Production Mode

When PRODUCTION=1:

• Builds static client files and serves them directly from the Node.js server
• Server runs compiled TypeScript from dist/ on port 8930
• No hot-reloading; requires rebuild for changes
• Database mounted for persistence

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

Building (for Production)

If you need to manually build the production image:

docker-compose build

This builds the image with server and client dependencies installed and built.

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.