# Development Notes

This guide covers setting up and working with the [vuer-rtc-workspace](https://github.com/vuer-ai/vuer-rtc-workspace) monorepo.

The reference server implementation uses MongoDB's change streams to provide
real-time updates to connected clients. This feature requires setting up a
replica set (the minimum requirement is 1 node *a.k.a.* **zero** replica).

I have automated this with `mprocs` for the orchestration, and docker compose
for the database.

## Packages

| Package | Description |
|---------|-------------|
| `@vuer-ai/vuer-rtc` | Core CRDT operations and client state management |
| `@vuer-ai/vuer-rtc-server` | MongoDB + Fastify server |
| `@vuer-ai/rtc-docs` | Documentation site |

## Quick Start

Get up and running in three simple steps. The dev environment spins up a MongoDB replica set (single node) and Redis via Docker, so you don't have to configure anything.

1. Clone and install dependencies:
   ```bash
   git clone https://github.com/vuer-ai/vuer-rtc-workspace
   cd vuer-rtc-workspace
   pnpm install
   ```

2. Start the full dev environment (Docker, server, and docs):
   ```bash
   pnpm dev
   ```

3. Run tests in a separate terminal:
   ```bash
   pnpm test
   ```

## Development Commands

```bash
# Full dev environment (docker + server + docs)
pnpm dev

# Individual services
pnpm dev:docs      # Docs site only
pnpm dev:server    # Server only (requires docker)

# Docker
pnpm docker:up     # Start MongoDB + Redis, run prisma push
pnpm docker:down   # Stop containers
pnpm docker:logs   # Tail container logs
pnpm docker:clean  # Remove containers + volumes
```

## Docker Makefile

More granular control via `make -C docker <target>`:

```bash
make -C docker up          # Start + prisma db push
make -C docker down        # Stop containers
make -C docker clean       # Remove containers + volumes
make -C docker clean-all   # Also remove images
make -C docker logs        # Tail all logs
make -C docker health      # Check mongo/redis status
make -C docker mongo-shell # Interactive mongosh
make -C docker redis-cli   # Interactive redis-cli
make -C docker db-push     # Push Prisma schema
```

## Database Schema

MongoDB with replica set (required for Change Streams):
- Connection: `mongodb://localhost:27017/vuer-rtc?replicaSet=rs0`
- Schema managed by Prisma (`packages/vuer-rtc-server/prisma/schema.prisma`)

Redis for pub/sub and caching:
- Connection: `redis://localhost:6379`

### Collections

| Collection | Purpose |
|------------|---------|
| **Document** | Scene metadata + `currentState` (schema-free JSON snapshot) |
| **Operation** | Individual CRDT operations with vector clocks for replay |
| **JournalBatch** | Batched write-ahead log (33ms Figma-style batching) |
| **Session** | Client connections, presence, and clock state |

```
┌──────────────────────────────────────────────────────────────────────┐
│                               MongoDB                                │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐  ┌────────────┐  │
│  │  Document   │  │  Operation  │  │ JournalBatch │  │ Session    │  │
│  │             │  │             │  │              │  │            │  │
│  │ currentState│  │ vectorClock │  │ operations[] │  │ presence   │  │
│  │ (JSON)      │  │ lamportTime │  │ startTime    │  │ clockValue │  │
│  │ version     │  │ data        │  │ endTime      │  │ connected  │  │
│  └─────────────┘  └─────────────┘  └──────────────┘  └────────────┘  │
└──────────────────────────────────────────────────────────────────────┘
```

**Key design choices:**
- `Document.currentState` is schema-free JSON - no fixed transform/properties fields
- Operations specify their own merge behavior via `ot` (e.g., `number.add`, `vector3.set`)
- JournalBatch enables 33ms batching for write reliability (Figma's approach)

## Testing

```bash
pnpm test           # All tests
pnpm test:vuer-rtc  # Core library tests
pnpm test:server    # Server tests
```

## Building

```bash
pnpm build          # Build all packages
pnpm build:packages # Build vuer-rtc + server only
```

## Deployment

```bash
pnpm deploy  # Push to netlify-production branch
```