feat: Replace y-webrtc with PartyKit for real-time collaboration

[Matia-R]

Summary

This PR replaces the peer-to-peer WebRTC sync (y-webrtc) with a server-mediated WebSocket architecture using PartyKit. This addresses several scalability concerns with the current CRDT implementation.

Problem

The current y-webrtc approach has limitations:

1. WebRTC mesh scaling: With 5 users × 3 instances = 15 peers, the mesh creates 105 WebRTC connections
2. Firewall issues: WebRTC P2P fails through many corporate firewalls with no fallback
3. Redundant saves: All clients independently save to database (N clients = N save streams)
4. Complex persistence: Append-only log + snapshots + compaction logic

Solution

PartyKit provides:

• Server-mediated sync: All clients connect to a central WebSocket server (star topology)
• Single persistence point: Only the PartyKit server writes to the database
• Reliable connectivity: WebSocket works through all firewalls
• RLS enforced: User's JWT flows through the system, maintaining existing permissions
• Simplified schema: Single document_state table instead of changes + snapshots
• Free tier: Runs on Cloudflare's edge network, free for small usage

Database Schema

Before (Complex):

document_changes -- Append-only Yjs updates (many rows per document)
document_snapshots -- Compacted state (one row per document)-- Plus compaction logic when changes > 100 rows

After (Simple):

document_state -- Full Y.Doc state (one row per document)-- No compaction needed

Architecture

┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Client A │ │ Client B │ │ Client C │
│ (w/ JWT) │ │ (w/ JWT) │ │ (w/ JWT) │
└──────┬──────┘ └──────┬──────┘ └──────┬──────┘
│ │ │
└───────────────────┼───────────────────┘
│ WebSocket + JWT
▼
┌────────────────────────┐
│ PartyKit Server │
│ - Verifies JWT │
│ - Manages Y.Doc │
│ - Single writer │
└───────────┬────────────┘
│ HTTP + JWT
▼
┌────────────────────────┐
│ Next.js API Routes │
│ (RLS enforced) │
└───────────┬────────────┘
▼
┌────────────────────────┐
│ Supabase │
│ (document_state) │
└────────────────────────┘

Security Model

1. User authenticates with Supabase, receives JWT
2. Client connects to PartyKit with JWT in query params
3. PartyKit verifies JWT is not expired
4. PartyKit calls API routes with user's JWT
5. API routes create Supabase client using that JWT
6. RLS automatically enforced - same permission model as before

No service role key needed.

UX Optimizations

• New documents: Instant feel - no loading skeleton, document created on first connection
• Existing documents: Delayed loading skeleton (500ms threshold) to avoid flicker on fast loads while providing feedback on slow loads

Migration

A migration script is included to convert existing documents from the old schema:

# Dry run
SUPABASE_SERVICE_ROLE_KEY="your-key" npx tsx scripts/migrate-to-partykit.ts --dry-run
# Actual migration
SUPABASE_SERVICE_ROLE_KEY="your-key" npx tsx scripts/migrate-to-partykit.ts

The script:

• Reconstructs full Y.Doc state from snapshot + changes
• Processes documents in batches
• Skips already-migrated documents (safe to re-run)
• Provides detailed progress and statistics

Files Changed

File	Purpose
partykit.json	PartyKit configuration
party/document.ts	PartyKit server (Yjs room handler, JWT verification)
src/hooks/use-collaborative-doc-partykit.ts	Client-side hook
src/app/api/partykit/load/route.ts	Load document state
src/app/api/partykit/save/route.ts	Save document state
src/utils/supabase/from-token.ts	Creates Supabase client from JWT
migrations/partykit_document_state.sql	New database table
scripts/migrate-to-partykit.ts	Migration script for existing documents

Documentation

• PARTYKIT.md - Quick-start setup guide
• PARTYKIT_ARCHITECTURE.md - Comprehensive architecture documentation including:
  • System architecture with diagrams
  • All user flows and edge cases
  • Security model details
  • UX optimizations
  • Caveats and limitations
  • Future considerations for multi-user collaboration
  • Data migration instructions

Setup

1. Run Database Migration

-- Run migrations/partykit_document_state.sql in Supabase

2. Environment Variables

NEXT_PUBLIC_PARTYKIT_HOST=localhost:1999# or chptr-collab.partykit.devPARTYKIT_SECRET=your-secret-hereAPP_URL=http://localhost:3000

3. Local Development

# Terminal 1
npm run dev
# Terminal 2
npm run dev:partykit

4. Deploy

npm run deploy:partykit
npx partykit env add APP_URL
npx partykit env add PARTYKIT_SECRET

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
chptr	Error		Aug 31, 2026 1:44am

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
auto_review:
drafts: true

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}