# 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

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

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

The repository includes a helper script `launch.sh` that wraps `docker compose` with sane defaults for this project. It sets a stable compose project name and the common compose files so you can run commands from the repo root without extra flags.

Common examples:

```bash
# Start the development stack (hot-reload client/server)
./launch.sh up

# Tail logs for the client
./launch.sh logs peddlers-client

# Show running services
./launch.sh ps

# Stop everything
./launch.sh down

# Build images (no cache)
./launch.sh build

# Start production mode (uses the 'prod' profile)
./launch.sh --production up
```

#### 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, use the helper which ensures the correct compose files and project name are used:

```bash
./launch.sh build
```

Or using docker compose directly (explicit project and files):

```bash
docker compose -p peddlers-of-ketran -f docker-compose.yml -f docker-compose.dev.yml build
```

### Environment Variables

Create a `.env` file in the project root with any required environment variables. Recommended variables used by the repository tooling:

- `COMPOSE_PROJECT_NAME` (optional) — project name to be used by `docker compose`. Defaults to `peddlers-of-ketran` in this repo helper.
- `COMPOSE_FILE` (optional) — colon-delimited list of compose files. Example: `docker-compose.yml:docker-compose.dev.yml`.
- `PRODUCTION` — set to `1` for production profile, `0` (or unset) for development.

The repository already appends these to `.env` for convenience. If you prefer to manage them yourself, remove or edit those lines in `.env`.

## Architecture

```plantuml
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

```json
{}
```

#### Response

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

## Configuration

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

```bash
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
```bash
curl -X POST http://localhost:8930/api/v1/games/
```

### Get Game Status
```bash
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/](https://delapouite.com/) and licensed as [CC-BY-3.0](https://creativecommons.org/licenses/by/3.0/).