# 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`.

```bash
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:

```bash
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:

```bash
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.

```bash
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:

```bash
# 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

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

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

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