DEV Community: Pyae Phyo Maung

Building a Zero-Backend P2P Live Collaboration System in React with Yjs and WebRTC

Pyae Phyo Maung — Sat, 19 Sep 2026 11:28:27 +0000

If you spin up an authoritative WebSocket server for a collaborative spreadsheet, two problems hit you immediately:

The Infrastructure Tax: You are now paying for idle socket connections, Redis pub/sub adapters, and persistent database sync pipelines for users who might just leave a tab open in the background.
The Data Liability: Translation catalogs regularly contain confidential unreleased feature keys, internal system copy, and proprietary strings. The moment those strings transit an unencrypted central server, you inherit compliance and breach blast-radius liabilities.

For JSON Link, I wanted zero backend hosting costs and absolute data sovereignty.

Here is how the browser-native peer-to-peer collaboration engine is engineered using Yjs CRDTs, WebRTC DataChannels, and Web Crypto (AES-GCM-256).

The State Topology: Serverless Mesh

Traditional collaborative apps route every mutation through a central coordinator:

Browser A  ──[WebSocket]──>  [Central Node + Redis/DB]  ──[WebSocket]──>  Browser B

Instead of managing server state, JSON Link runs a direct peer-to-peer data mesh:

Browser A  <══════ WebRTC DataChannel (Direct P2P) ══════>  Browser B
                     │                                │
                     └─── [Ephemeral Signaling Nodes] ───┘

Signaling is strictly for discovery: Public STUN and WebSocket signaling servers only broker the initial SDP offer/answer handshake and ICE candidates. No document payload is ever stored on signaling nodes.
Direct browser transport: Once ICE negotiation completes, peers stream raw delta updates over SCTP-based WebRTC DataChannels. Latency drops to direct network ping (<20ms on LAN/regional connections).
Deterministic CRDT convergence: Concurrent keystrokes on the same table cell resolve automatically using Yjs state vectors and Lamport timestamps. There is no "last-write-wins" database overwrite.

Zero-Knowledge Signaling: Client-Side PBKDF2 + AES-GCM

Because public WebRTC signaling nodes can inspect transit packets during connection setup, room updates must be encrypted before leaving the browser.

When a room password or PIN is configured, the browser derives an AES-GCM 256-bit encryption key using PBKDF2-SHA256 with 100,000 iterations:

export async function deriveRoomKey(password: string, roomSalt: string): Promise<CryptoKey> {
  const enc = new TextEncoder();
  const keyMaterial = await crypto.subtle.importKey(
    'raw',
    enc.encode(password),
    { name: 'PBKDF2' },
    false,
    ['deriveKey']
  );

  return crypto.subtle.deriveKey(
    {
      name: 'PBKDF2',
      salt: enc.encode(roomSalt),
      iterations: 100000,
      hash: 'SHA-256',
    },
    keyMaterial,
    { name: 'AES-GCM', length: 256 },
    false,
    ['encrypt', 'decrypt']
  );
}

Every Yjs document delta is encrypted client-side with a unique 12-byte initialization vector (IV) before transmission. Even if an intermediary intercepts the signaling room traffic, all payloads remain opaque ciphertext.

Integrating Yjs into a Reactive Spreadsheet Grid

Binding CRDT updates to a React spreadsheet without triggering render thrashing requires separating the document state from ephemeral collaboration presence:

import * as Y from 'yjs';
import { WebrtcProvider } from 'y-webrtc';

const ydoc = new Y.Doc();
const yTranslations = ydoc.getMap('translations');

// Establish encrypted P2P mesh across fallback signaling clusters
const provider = new WebrtcProvider('json-link-room-id', ydoc, {
  signaling: [
    'wss://y-webrtc.fly.dev',
    'wss://y-webrtc-signaling.fly.dev'
  ],
  password: roomPin, // Native PBKDF2-SHA256 derivation under the hood
});

// 1. Synchronize CRDT changes into the table model
yTranslations.observe(() => {
  setGridData(yTranslations.toJSON());
});

// 2. Ephemeral awareness (multiplayer cursors & focused cells)
provider.awareness.setLocalStateField('user', {
  name: 'Alex-42',
  color: '#10b981',
  pointer: { x: clientX, y: clientY },
  activeCell: { key: 'auth.login.title', field: 'en' }
});

Where P2P Sucks (And How to Mitigate It)

Full-mesh WebRTC is not magic; it comes with real-world engineering constraints:

The $O(N^2)$ Bandwidth Limit: In a full mesh, every peer connects to every other peer. For 3–6 collaborators working on a localization file, overhead is negligible (a few KB/s). Beyond 10–12 peers, upstream bandwidth multiplies rapidly. For JSON Link's target use-case (small product pods localizing software), full mesh is the sweet spot.
NAT / Corporate Firewall Traversal: Strict symmetric NATs block direct peer-to-peer hole-punching. We bundle public STUN endpoints (stun:stun.l.google.com:19302) for standard NAT mapping, with self-hostable signaling flags for teams behind strict corporate firewalls.
Offline Resilience & AST Protection: When a peer disconnects, their edits persist locally via the File System Access API (direct two-way disk synchronization with locales/*.json). On reconnect, Yjs automatically replays missing updates. To prevent non-technical contributors from accidentally breaking translation variables, an AST tokenizer locks ICU MessageFormat ({count, plural, ...}), Mustache, and Printf placeholders into immutable chips during live editing.

Code & Architecture

JSON Link is MIT licensed and runs 100% in the browser with no backend dependencies:

Live App: https://json-link.pages.dev
Source Code: https://github.com/pyaephyomaungdev/json-link
Test Suite: 463 automated tests across 60 test suites (Vitest + React Testing Library)

The Hidden Failure Modes in Localization Infrastructure (And Why We Architected a Local-First Solution)

Pyae Phyo Maung — Sat, 12 Sep 2026 14:55:42 +0000

In scaling cross-platform codebases across Flutter, React, iOS, and Android, localization (i18n) is frequently treated as an operational afterthought. Engineering teams default to Google Sheets, manual CSV exports, or enterprise cloud translation SaaS.

From a systems engineering perspective, this workflow introduces significant production vulnerabilities:

Syntax Corruption & Runtime Exceptions: Non-technical translators or generalist AI models routinely corrupt or delete interpolation tokens ({username}, %1$s, {{count}}). When compiled into production builds, missing arguments trigger uncaught exceptions and mobile app crashes.
Repository Drift & Multi-Format Hell: Mobile and web codebases consume fundamentally different formats: Flutter requires ARB (app_en.arb) with @key metadata; iOS requires .strings; Android requires XML resources (strings.xml); modern frontend stacks require TypeScript-typed JSON. Manual conversion leads to untracked key mismatches and broken CI pipelines.
Data Residency & Credential Exposure: Uploading proprietary product copy and unreleased feature strings to third-party translation clouds creates compliance friction and attack surface. Furthermore, managing third-party AI keys on shared backend servers introduces avoidable operational risk.

To solve this friction at the architectural level, we designed and open-sourced JSON Link — a zero-backend, local-first localization workstation.

Architectural Design Decisions

1. Deterministic AST Token Isolation

ICU / Mustache / Printf Scanner -> Recursive-descent AST parser -> Locked visual tags

Translation cells isolate parameter placeholders so translators cannot accidentally alter them. The engine validates variable parity across source and target strings in real time.

2. Local-First Direct Disk Sync

Browser Memory -> Native File System Access API -> Atomic disk writes

Instead of forcing developers to download and unpack ZIP files, JSON Link binds directly to local project directories (e.g., src/locales or assets/l10n). A single click updates all language files simultaneously on disk.

3. Client-Side Cryptographic Isolation (BYOK OpenRouter)

API Credentials -> AES-GCM 256-bit encryption (Web Crypto API + PBKDF2) -> Client-side persistence

Zero intermediary servers exist between the browser and OpenRouter. Keys and translation payloads never transit an intermediary cloud proxy.

4. Zero-Knowledge Workspace Sharing & Team Handoff (.jsonlink)

Collaborating across distributed teams usually requires setting up accounts or uploading data to shared cloud databases. We avoided that entirely:

Zero-Storage Instant URL Sharing (#share=...): Compresses entire multi-language workspace payloads in-browser using DEFLATE (pako) and packs them directly into the URL hash fragment. Plaintext data never transits or resides on any backend.
Client-Side AES-GCM 256-bit Password Encryption: Optional password protection available for both Instant URLs and standalone .jsonlink project files. Key derivation utilizes PBKDF2 with SHA-256 (100,000 iterations, 16-byte random salt, and 12-byte initialization vector).
Full Encryption Parity Across the App: Integrated across all touchpoints including ShareModal (Team Handoff), SaveProjectModal (File -> Save Project), and ExitConfirmDialog (Home save guard).
Automated Decryption Dialog: Visiting an encrypted share URL or uploading a password-protected .jsonlink file triggers the UnlockShareDialog. Cryptographic authentication tag verification detects incorrect passwords or tampered ciphertext with immediate feedback.

5. Southeast Asian Font Encoding Engine

Rabbit Algorithm Heuristics -> Syllable / consonant reordering -> Lossless Zawgyi <-> Unicode conversion

Prevents font rendering corruption on legacy Android forks and ensures strict compliance with standard Myanmar Unicode.

6. stdio JSON-RPC 2.0 Model Context Protocol (MCP) Server

Claude Desktop / Cursor -> stdio JSON-RPC 2.0 -> Automated linting, parsing, and bundle compilation

Enables autonomous AI coding agents to inspect, validate, and compile localization bundles directly within developer IDE environments.

Verification & Reliability Baseline

308 Automated Tests across 42 Test Suites executed via Vitest and enforced on every pull request via GitHub Actions CI (204 core library tests + 104 UI integration tests).
100% Offline Capability: Packaged with a Service Worker and Web App Manifest as a standalone installable desktop PWA.
Open Source: Licensed under MIT with zero telemetry and zero tracking scripts.

If your team is managing multi-platform localization, review the architecture and codebase here:

Repository: https://github.com/pyaephyomaungdev/json-link
Live Demo: https://json-link.pages.dev