peddlers-of-ketran/README.md

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

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.