Real-Time Collaboration & Preview

Sitepins provides two advanced real-time systems:

Real-Time Collaboration: Powered by Yjs CRDTs over Hocuspocus WebSockets and Socket.IO presence gateways.
Interactive Live Preview: Runs user site generators (Astro, Next.js, Hugo, etc.) inside isolated sandbox VMs.

1. Real-Time Collaboration Architecture

Two independent real-time layers run concurrently on the Express server:

System	Protocol	Path	Data Transferred
Hocuspocus (Yjs)	Raw WebSocket (`ws`)	`/api/v1/editor/collab`	Document content: Yjs CRDT delta operations, remote awareness carets, and inline cursor positions.
Socket.IO	Engine.IO / Polling / WS	`/socket.io/`	Session metadata: Who is looking at a file, user avatars, and commit notifications.


┌─────────────────────────────────────────────────────────┐
│                   Plate Visual Editor                   │
└────────────┬───────────────────────────────┬────────────┘
             │ Yjs CRDT Operations           │ Awareness & Commits
             ▼                               ▼
┌───────────────────────────┐   ┌─────────────────────────┐
│ Hocuspocus Server         │   │ Socket.IO Server        │
│ (/api/v1/editor/collab)   │   │ (/socket.io/)           │
├───────────────────────────┤   ├─────────────────────────┤
│ Document Authorization    │   │ Presence Gateway        │
│ In-Memory CRDT Debounce   │   │ Commit Gateway          │
└────────────┬──────────────┘   └────────────┬────────────┘
             │                               │
             ▼                               ▼
┌─────────────────────────────────────────────────────────┐
│                    MongoDB Database                     │
│    (Tenant Membership Validation: isOrgMember)          │
└─────────────────────────────────────────────────────────┘

Document Naming & Tenant Isolation

Document names follow a strict virtual path:


/org-<orgId>/<projectId>/<filePath>

When a client initiates a WebSocket handshake to Hocuspocus:

The server reads the HTTP session cookie from the upgrade request headers.
It parses the <orgId> segment from the document URI.
It queries MongoDB using isOrgMember(userId, orgId).
If the user is not a verified member of that organization, the socket is immediately terminated with 403 Forbidden.

This ensures multi-tenant security: a user cannot inspect or edit another organization’s files by simply guessing document paths.

Presence Gateway

The presence gateway (api/src/modules/common/presence.gateway.ts) tracks active viewers:

Room Key: presence:<orgId>:<projectId>:<filePath>
Multi-Tab Deduplication: If a user opens the same document across multiple browser tabs, their user avatar is displayed once. The user is only removed from the roster when their last open connection closes.
Identity Safety: Identity metadata (name, avatar, email) is resolved directly from the authenticated session, not from client-sent payloads.

Commit Notification Gateway

When a collaborator saves or publishes changes, the client emits commit over Socket.IO:

The server validates that the socket has joined the target editor room (join-editor).
The server broadcasts commit:completed with the author’s name, commit SHA, and timestamp to all other active editors in the room.
Other users’ interfaces immediately notify them that the remote file has updated.

2. Live Preview & Sandbox Architecture

Rather than rendering an approximate Markdown preview, Sitepins runs your real static site generator in an isolated Vercel Sandbox (a disposable microVM).


┌──────────────────────────┐
│  Browser Editor          │
│  (Unsaved Changes)       │
└────────────┬─────────────┘
             │ Quick Op (Shell write)
             ▼
┌──────────────────────────┐
│  Next.js API Handler     │
│  (/api/sandbox/create)   │
└────────────┬─────────────┘
             │ Vercel Sandbox SDK
             ▼
┌─────────────────────────────────────────────────────────┐
│  Vercel Sandbox Linux MicroVM                           │
│  ┌───────────────────────────────────────────────────┐  │
│  │ 1. Git clone at branch                            │  │
│  │ 2. Install toolchain (Node, Go, Hugo)             │  │
│  │ 3. Patch dev scripts (0.0.0.0 host binding)       │  │
│  │ 4. Run generator dev server (e.g. astro dev)      │  │
│  │ 5. Expose public preview URL                      │  │
│  └───────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────┘

Supported Site Generators

The sandbox system automatically inspects your project configuration and adapts its dev command and toolchain:

Generator	Default Port	Environment & Toolchain Handling
Next.js	`3000`	Injects Next.js reload bridge; enables draft environment mode.
Astro	`4321`	Patches scripts with `--host 0.0.0.0`; self-refreshing HMR.
Hugo	`1313`	Dynamically installs Go and Hugo extended binary on cold start.
Hugo (exampleSite)	`1313`	Accommodates nested theme `exampleSite/` root paths.
TanStack Start	`3000`	Injects TanStack reload bridge.
SvelteKit / Vite	`5173`	Binds to `0.0.0.0` for container reachability.
Jekyll	`4000`	Runs static generator dev loop.
Hexo	`3000`	Static asset generator mode.

Sandbox Lifecycle & Resiliency Engine

1. Cold Start & Resource Allocation

Triggered when opening preview for the first time:

Allocates 4 vCPUs (8GB RAM) with automatic tier fallback, ensuring Vite, Astro SSR, and image transformations have ample compute without CPU starvation.
Checks MongoDB (/api/v1/project-preview/:projectId) for an active sandbox session.
Clones the repository at the project’s current working branch.
Detects package manager (pnpm, npm, yarn, or bun) and runs install.
Pre-exposes common ports ([port, 1313, 4321, 3000, 5173]) so edge routing is immediately available regardless of framework port shifts (e.g. Hugo on 1313, Astro on 4321, Vite on 5173).
If Hugo is detected, downloads, caches, and verifies the Go and Hugo toolchains before boot to avoid missing-binary crashes.
Patches dev scripts to bind to 0.0.0.0 for external routing.
Starts the dev server with in-container TCP socket health probes (127.0.0.1:${port}) and lightweight HTTP ping probes (/__vite_ping, /favicon.ico).
Monitors /tmp/devserver.log for early crash errors to fail fast (~3s) with actionable diagnostic logs rather than hanging until timeout.
Generates the secure public preview URL.

2. Warm Updates (Quick Ops)

As you type in the editor, Sitepins executes debounced quick updates:

Uncommitted edits are streamed directly into the VM’s file system.
The generator’s native hot module reloading (HMR) repaints the preview in real time without restarting the server or creating Git commits.

3. Heartbeat Keep-Alive & Session Preservation

Active previews send a heartbeat ping every 5 minutes (POST /api/sandbox/heartbeat).
Sessions are capped at 45 minutes to conserve quota.
Sitepins checks if preview browser tabs are actively open before sending deallocation beacons, ensuring tab reloads do not prematurely terminate live sessions.

Organization Sandbox Credentials

To enable live preview in your organization:

Navigate to Organization Settings → Sandbox Preview.
Input your Vercel Access Token and Project details.
Sitepins encrypts the token at rest using AES-256-GCM via SANDBOX_ENCRYPTION_KEY.