# 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 (using docker compose)

This project runs directly with the Docker Compose CLI from the repository root. Examples:

```bash
# Development (hot-reload client/server)
PRODUCTION=0 docker compose up -d --profile dev

# Production (static build served by the server)
PRODUCTION=1 docker compose up -d --profile prod

# Tail logs for the client/service
docker compose logs -f peddlers-client

# Show running services
docker compose ps

# Stop everything and remove orphans
docker compose down --remove-orphans

# Build images
docker compose build

### Ensuring container-created files match your host UID/GID

When running containers that mount the workspace (dev/test), files created by the container may be owned by root which can be inconvenient on the host. To avoid this, images in this repo accept build-time args `HOST_UID` and `HOST_GID` and create a matching user inside the image. Set these to your current UID/GID before building so runtime-created files use your ownership.

Example (bash):

```bash
export HOST_UID=$(id -u)
export HOST_GID=$(id -g)
# Build images with the host UID/GID baked in
docker compose build peddlers-test peddlers-of-ketran peddlers-client peddlers-of-ketran-dev

# Then run in dev mode as usual (hot-reload):
PRODUCTION=0 docker compose up -d --profile dev
```

If you prefer to set these in `.env`, add `HOST_UID=...` and `HOST_GID=...` to the file in the repo root.
```

#### 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)

To manually build the production image:

```bash
docker compose build peddlers-of-ketran
```

### 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/).