npm package: @smoothglue/sync-whiteboard
Description: A minimal sync server for tlDraw based whiteboards
Author: Wade Tait
Latest version: 1.1.2

## @smoothglue/sync-whiteboard

A real-time collaborative whiteboard server designed to provide a realtime, collaborative whiteboard experience for frontends integrated with [tldraw](https://tldraw.dev/). It functions as a microservice, handling websocket connections to sync shared whiteboard edits in real-time using tldraw's [sync-core](https://www.npmjs.com/package/@tldraw/sync-core) library.

## Overview

The core responsibilities of this service include:

- Managing WebSocket connections for real-time synchronization of whiteboard edits.
- Facilitating data persistence (snapshots) via a backend API.
- Handling storage of assets (like images or videos) via a backend API.

## Features

- **Real-time Collaboration:** Leverages WebSockets and `@tldraw/sync-core` for multi-user interaction on a shared whiteboard via Fastify and `@fastify/websocket`.
- **Snapshot Persistence:** Delegates saving and loading whiteboard state snapshots to a configurable backend service. The development environment includes a mock backend for this.
- **Asset Handling:** Delegates uploading and retrieving large binary assets to a configurable backend service. The development environment includes a mock backend for this.

## Architecture

This service is designed as a NodeJS microservice that connects to client applications using tldraw via WebSockets for real-time data synchronization. It relies on external services (configurable via environment variables) for persisting snapshots and storing assets.

## Installation

```bash
npm install @smoothglue/sync-whiteboard
# or
yarn add @smoothglue/sync-whiteboard
```

## Configuration
The @smoothglue/sync-whiteboard server is configured entirely through the environment variables listed below:

| Environment Variable             | Description                                                                                                    | Default Value | Required |
| :------------------------------- |:---------------------------------------------------------------------------------------------------------------| :------------ |:---------|
| `SWB_PORT`                       | The port on which the server will listen.                                                                      | `5858`        | No       |
| `SWB_HOST`                       | The host address the server will bind to.                                                                      | `0.0.0.0`     | No       |
| `SWB_LOG_LEVEL`                  | The minimum log level for messages (e.g, `fatal`, `error`, `warn`, `info`, `debug`).                           | `info`        | No       |
| `SWB_SNAPSHOT_STORAGE_URL`       | **Crucial:** The base URL for the service responsible for persisting tldraw room states.                       | (None)        | **Yes**  |
| `SWB_ASSET_STORAGE_URL`          | **Crucial:** The base URL for the service responsible for storing and retrieving tldraw assets (e.g., images). | (None)        | **Yes**  |
| `SWB_SAVE_INTERVAL_MS`           | The interval (in milliseconds) the server periodically checks for and saves updated room snapshots.            | `5000`        | No       |


## Usage

This package provides a server that can be integrated into your application or run as a standalone service.

### Integrating with your Application
You can `require`/`import` the package directly into your Node.js application. Upon import, the server will attempt to start, binding to the host and port configured via environment variables.

```javascript
// Example application's entry point: (e.g., app.js or index.js)
// Imports the package, which initializes and starts the sync server.
require('@smoothglue/sync-whiteboard');
```

### Running as a Standalone Service (e.g., in Docker)
To run the `@smoothglue/sync-whiteboard` server as a standalone process, execute its main entry point. This is typically done within a Docker container where environment variables are easily managed.

From your containerized Node.js environment with dependencies installed, your CMD or ENTRYPOINT in the Dockerfile would look like this:

```dockerfile
# Dockerfile snippet example
# ... (setting up Node.js, copying package.json, running npm install)
# The 'dist/server.js' file is the compiled entry point of the @smoothglue/sync-whiteboard package.
CMD ["node", "node_modules/@smoothglue/sync-whiteboard/dist/server.js"]
```

## Development Environment (Docker)

This project includes a Docker-based development environment configured in `dev-env/docker-compose.yml`. This makes it easy to run the `sync-whiteboard` server along with its dependencies (mock backend API, database, object storage) and a mock frontend client.

### Prerequisites:

- Docker ([https://www.docker.com/get-started](https://www.docker.com/get-started))
- Docker Compose ([https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/))

### Configuration (Optional):

If you wish to alter the default sync-whiteboard server configuration, refer to the following steps.

1.  Navigate to the `dev-env` directory:
    ```bash
    cd sync-whiteboard/dev-env
    ```
2.  Copy `env.example` to `.env` and adjust settings as needed. This file configures services like the database and object storage services expressed within `docker-compose.yml`. For `sync-whiteboard` specific settings, see the [Configuration](#configuration) section above.

### Running the Environment:

1.  From the `dev-env` directory, run:
    ```bash
    docker-compose up --build
    ```

### Services:

The Docker Compose setup starts the following services:

| Service Name         | Description                                                          | Accessible At (Host)                            |
| :------------------- | :------------------------------------------------------------------- |:------------------------------------------------|
| `sync-whiteboard`    | The main Node.js sync server for real-time whiteboard collaboration. | `ws://localhost:5858`                           |
| `mock-backend`       | A Flask-based API simulating backend storage for snapshots & assets. | [http://localhost:5001](http://localhost:5001) |
| `postgres`           | PostgreSQL database for the mock backend's snapshot storage.         | `localhost:5433`                                |
| `minio`              | MinIO object storage for the mock backend's asset storage.           | [http://localhost:9001](http://localhost:9001)  |
| `mock-frontend`      | A simple Vite+React client for testing the whiteboard functionality. | [http://localhost:8080](http://localhost:8080)  |