Development Notes

This guide covers setting up and working with the 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/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.

Clone and install dependencies:

git clone https://github.com/vuer-ai/vuer-rtc-workspace
cd vuer-rtc-workspace
pnpm install

Start the full dev environment (Docker, server, and docs):
```
pnpm dev
```
Run tests in a separate terminal:
```
pnpm test
```

Development Commands

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

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/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 otype (e.g., number.add, vector3.set)
JournalBatch enables 33ms batching for write reliability (Figma's approach)

Testing

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

Building

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

Deployment

pnpm deploy  # Push to netlify-production branch