Web Apps & Utilities

Last updated Jun 2026

Project Q&A Knowledge Base

Overview

Private Collab Whiteboard is a real-time collaborative drawing app that prioritizes privacy. It lets multiple users draw on a shared canvas simultaneously, with all data synced peer-to-peer through CRDTs and optionally encrypted end-to-end. No account required — just create a room and share a link. The interesting part is access control: encrypted rooms use capability links (owner / editor / viewer) whose permissions are enforced by ECDSA signatures verified between peers, so view-only actually means view-only even though there's no server to ask. All drawing data lives in the browser (IndexedDB), and the relay is a minimal broadcast server that never sees plaintext.

Key Features

Real-time Collaboration: CRDT-based sync via Y.js with live cursor tracking, live drawing previews, and user presence indicators
Drawing Tools: Freehand pencil and highlighter; lines, arrows, rectangles, circles, ellipses, diamonds, and triangles with solid/dashed/dotted strokes and optional fills; a text tool; color-coded sticky notes with wrapped, scrollable text; shape connectors that stay bound to the shapes they link; and an ephemeral laser pointer for presentations
Save as PNG / PDF: An interactive export modal renders the board to an off-screen canvas and lets you pan/zoom to frame the export before saving a retina-resolution PNG or a single-page PDF
Infinite Canvas: Pan (Space+drag), zoom (scroll wheel or buttons), and fit-to-content with a virtual coordinate system
End-to-End Encryption: Optional password protection using AES-256-GCM with PBKDF2 key derivation (600K iterations) and a random per-room salt carried in the capability link
Capability-Based Roles: Encrypted rooms issue owner / editor / viewer links; the role is carried (and enforced) by which signing keys the link contains, not a flag the client can flip
Cryptographic View-Only: Viewers hold no signing key, so peers reject any edit they try to make — view-only survives a hostile viewer editing the URL or the JS
Owner-Controlled Rotation: Only the owner can rotate the room to a new epoch (via change-password), instantly invalidating older links
Select & Manipulate: Select, move, resize shapes; multi-select with Shift+click; copy/paste/duplicate; lock shapes
Undo/Redo: CRDT-aware undo that only affects your own changes, never other users'
Multiple Boards: Create, switch between, clear, and delete separate boards within a single room
Offline Support: Full offline drawing with automatic sync when reconnected via IndexedDB persistence
Board History: "My Boards" page tracks all rooms you've visited with role badges and access counts

Technical Highlights

Signed-Update Sync Layer with Cryptographic View-Only

Encryption hides content from the server, but everyone with the room password can still decrypt — so a view-only link that just sets a client flag is bypassed by editing the URL or the JS. I replaced Y.js's stock document-sync protocol with a thin custom layer (signed-doc-sync.js + protocol.js): editors sign each Y.js update with a per-epoch ECDSA P-256 key over epoch ‖ update (epoch-prefixed to block replay), and every peer verifies the signature against the room's certified editor key before applying it. Viewers are simply never handed a signing key, so any update they emit fails verification at every honest peer and never lands in the shared document. Y.js still does all the CRDT conflict resolution; only the transport framing is mine. The underlying transport (sync-provider.js) AES-256-GCM-encrypts every frame before it hits the PartyKit relay.

CRDT-Aware Undo/Redo

The undo system uses Y.js's built-in UndoManager, which only tracks local changes. This means pressing Ctrl+Z never undoes another user's work — a subtle but critical UX detail for collaborative editing. Changes within 500ms are grouped into a single undo step to match user intent (e.g., a quick series of shape moves becomes one undo).

Infinite Canvas with World/Screen Coordinate Transform

The drawing system maintains a virtual world coordinate system separate from screen pixels. All shapes are stored in world coordinates, and a viewport transform (pan + zoom) converts between the two. This enables smooth zooming centered on the cursor position, fit-to-content, and consistent shape sizes regardless of zoom level. Touch/pinch-to-zoom is also supported for mobile.

Defense-in-Depth Against Peer-Injected XSS

In a P2P app the dangerous input isn't a form field — it's the shared document. Shape objects, user names, and presence state all arrive from untrusted peers over the CRDT and several of them get interpolated into innerHTML (the shape-settings popup header, cursor labels, the board list). I closed this on two layers. First, an allow-list sanitization layer in utils.js/shape-schema.js: safeColor rejects anything that isn't a plain #hex value, safeNumber rejects non-finite/non-numeric input, safeToolName collapses unknown tool names to an inert literal, and escapeHtml is now a single shared implementation (three modules had drifted copies, one of which forgot to escape quotes). sanitizeShape runs an untrusted shape through all of these before any DOM-bound field is read. Second, the CSP in vercel.json was tightened to script-src 'self' with no unsafe-inline, so even a missed sink can't execute an injected <script> — which in turn forced the previously-inline page bootstraps out into real modules (index-home.js, boards-home.js).

Owner Root-of-Trust and P2P Revocation

The hard problem in a serverless system is revocation: if the editor key is just embedded in links, there's no authority to ask "is this link still allowed?" My answer is a two-tier PKI rooted in a per-room owner ECDSA keypair (room-cert.js). The owner key signs an epoch certificate binding the current editor public key to an epoch number, and peers only trust an editor key that a valid owner cert vouches for (signed-doc-sync.js verifies this once on start and fails closed if the cert doesn't pin the exact editor key it's verifying against). Because only the owner holds the owner private key, only the owner can mint a new epoch. Rotating the room mints epoch N+1 with a fresh editor key and broadcasts an owner-signed rotate notice; peers mark the old epoch superseded and stop applying its updates, so anyone holding an old link can no longer produce edits anyone will accept — real revocation with no central server. The owner link itself is never shared, so editors can draw but can't rotate.

Relationship-Bound Connectors over a CRDT Shape Array

Connectors are the one shape that isn't self-contained: an arrow between two boxes has to follow those boxes as they move, across clients, with no shared mutable pointer. I store a connector as {fromId, toId} referencing the IDs of the shapes it links, and resolve the actual endpoint geometry at render time (connector-geometry.js): nearestAnchors picks the closest pair of edge anchors between the two bounding boxes so the line attaches sensibly, and the renderer re-derives those points every frame. Because endpoints are computed, not stored, a peer moving a box on another client just changes that box's coordinates — every connector touching it re-routes automatically when the CRDT update lands, with no separate "update the connector" message. danglingConnectorIndices finds connectors whose referenced shapes were deleted so they can be cleaned up, and connectors are forbidden from binding to other connectors to avoid resolution recursion. Keeping all of this geometry in a pure, DOM-free module means it's exhaustively unit-tested (connector-geometry.test.js) without a canvas.

Pure, Browser-Free Logic Modules for Testability

A canvas app tempts you to bury arithmetic inside event handlers and requestAnimationFrame callbacks where it can only be tested by driving a real browser. Instead, the non-trivial logic is extracted into pure modules that take plain values and return plain values: draw-geometry.js (hit-testing, polygon point generation, arrowhead math, dash patterns, a spatial shape index), text-wrap.js (word-wrap and scroll-extent math shared by the text tool and sticky notes), connector-geometry.js, keyboard-intent.js (the decision of whether a Delete keypress should consume the event), and laser-trail.js (trail pruning by timestamp). Each has a focused Vitest file and runs with no DOM. The impure shell — drawing.js, app.js — wires these to the canvas and the Y.Doc. This is what lets the test suite cover real behavior (does a point fall inside this rotated triangle? does a tampered tool name collapse to an inert literal?) instead of just crypto round-trips.

Engineering Decisions

Transport: WebSocket relay over peer-to-peer WebRTC

Constraint: Needed reliable real-time sync across arbitrary networks (corporate firewalls, mobile carriers, double-NAT home routers) while keeping the server out of the trust boundary.
Options: y-webrtc peer-to-peer mesh, a self-hosted Y.js WebSocket server, or PartyKit's Cloudflare-Workers relay.
Choice: PartyKit relay (party/index.ts) with all payloads encrypted client-side.
Why: WebRTC's NAT traversal failed too often in practice. A broadcast relay is simpler and reaches everywhere a WebSocket reaches, and because messages are AES-256-GCM encrypted before they leave the browser, the relay never sees plaintext — the privacy model survives the migration.

Lazy default-board creation over eager initialization

Constraint: When each client independently ran boards.set('default', new Y.Array()) on load, two joiners created competing default entries in the boards Y.Map. The CRDT resolves the conflict by picking a winner by random client ID, which could orphan the array that actually held the drawings — content would sync at the byte level but never render.
Options: Gate creation behind a sync timeout, lock creation to the owner, or never create the board eagerly and let the first write create it.
Choice: Don't create default at init at all (yjs-setup.js); drawing.js lazily creates it on the first drawn shape, and the drawing observer re-subscribes if the board array instance changes underneath it.
Why: A joiner receives the editor's existing array via snapshot and never races to create a competing one, so there's no Y.Map conflict to orphan content. It also avoids inventing roles or a timeout heuristic for what is really a "who creates the seed object" problem.

Multi-page Vite build over an SPA shell

Constraint: Three pages with very different payloads — a marketing landing page, a board-history list, and the heavy whiteboard runtime (Y.js + canvas engine + crypto).
Options: Single-page app with a router and code-splitting, or Vite's MPA mode with one HTML entry per page.
Choice: MPA — index.html, boards.html, room.html each ship their own bundle, with Vercel rewrites mapping /room/:id to room.html.
Why: The landing page loads in a couple of KB without dragging in Y.js, and there is no shared client-side state worth preserving across navigations. Routing collapses into a static rewrite rule.

Capabilities in the URL fragment, enforced by signatures

Constraint: View-only had to be tamper-proof against a hostile viewer — someone who has the password, can decrypt, and will edit the URL or patch the client JS — without introducing accounts or a server-side auth check (the relay is intentionally dumb).
Options: A client-side readOnly flag (bypassable), a weak "signature" over the role string (still bypassable — nothing verifies it at write time), server-issued JWTs (breaks the dumb-relay/P2P model), or capability links where the absence of a key is the enforcement.
Choice: Encode the role's keys into the URL fragment — viewer links carry only public keys, editor links add the editor private key, owner links add the owner private key — and have every peer verify each update's signature before applying it (room-manager.js, signed-doc-sync.js).
Why: There's nothing to "flip." A viewer can't sign edits because they don't have the key, and editing the URL can't conjure one. Fragments never reach the relay, the model stays accountless, and trust is rooted in the owner key rather than a shared secret. (Older link formats are intentionally not honored — a hard version break, since a weaker legacy format would be a downgrade path.)

Frequently Asked Questions

How does the real-time sync work without a database?

Y.js uses CRDTs (Conflict-free Replicated Data Types) — a mathematical model where every edit has a globally unique ID and timestamp. When two users make concurrent edits, the CRDT merge algorithm guarantees both arrive at the same final state without any server-side conflict resolution. The Y.Doc is persisted to IndexedDB for offline access and synced over WebSockets through a simple broadcast relay.

Why vanilla JavaScript instead of React/Vue/Svelte?

The core of this app is an HTML5 Canvas — all drawing happens via imperative Canvas API calls, not DOM manipulation. A reactive framework would add overhead without benefit for the canvas rendering. The small amount of DOM UI (toolbars, modals, side panel) is simple enough to manage with direct DOM APIs, and it keeps the bundle small.

How does the encryption actually protect my data?

When you set a room password, the app derives an AES-256-GCM key using PBKDF2 (600,000 iterations of SHA-256, following current OWASP guidance) against a random 16-byte salt minted for that room. Both the iteration count and the salt ride in the capability link so every peer derives the same key, and the count is clamped to a [100k, 5M] range on decode — a tampered link can neither downgrade derivation below the legacy floor nor pin you to a multi-second one. Every Y.js sync message is encrypted with a random 12-byte IV before being sent over the WebSocket. The PartyKit server only ever sees encrypted binary blobs — it can't read shape data, text, cursor positions, or even user names. Only clients with the correct password can decrypt.

What happens if two users edit the same shape simultaneously?

Y.js handles this at the CRDT level. Each shape is a JSON object in a Y.Array. If two users modify the same shape property (e.g., both move a rectangle), Y.js's last-writer-wins semantics apply per field. If they modify different properties (one resizes, one recolors), both changes are preserved. The system is designed so conflicts are rare and resolution is invisible.

How does undo work in a collaborative environment?

The undo system uses Y.js's UndoManager, which tracks which changes were made by the local user. When you press Ctrl+Z, it only reverts your own recent action — it never touches other users' changes. This prevents the common collaborative editing frustration where one user's undo erases another user's work.

How does view-only mode actually stop a determined viewer?

It doesn't rely on the viewer's client behaving. A viewer link contains only public keys — no editor signing key. Edits in an encrypted room must be signed with the per-epoch editor key and are verified by every peer before being applied (signed-doc-sync.js). So even if a viewer edits the URL, opens dev tools, and forces their own client into "edit mode," the updates they broadcast carry no valid signature and every other peer drops them. The UI also hides editing controls for viewers, but that's cosmetic — the real enforcement is the missing key.

What's the difference between the owner, editor, and viewer links?

All three are capability links carried in the URL fragment. A viewer link has public keys only (can read, can't sign). An editor link adds the editor private key (can read and draw). An owner link adds the owner private key as well (can read, draw, and rotate the room). The owner link is never shared by the app — it stays in the creator's address bar — so editors can collaborate but can't lock anyone out or rotate the room.

How does rotating / revoking access work without a server?

Rotation is owner-only. Changing the password mints a new epoch (epoch N+1) with a fresh editor key, and the owner key signs a new certificate for it. The owner broadcasts an owner-signed rotate notice; current peers verify it against the owner public key, mark the old epoch superseded, and stop applying its updates. The owner is reloaded into the new link to re-share with whoever should keep access. Anyone holding an old link can still decrypt old cached state but can no longer produce edits that peers will accept — the practical effect of revocation, achieved with signatures instead of a central authority.

What happens if someone tampers with or truncates a capability link?

The link parser fails closed. parseCapabilityHash (room-manager.js) distinguishes three cases: no fragment at all is an intentional open room and returns null; a present-but-undecodable fragment throws rather than silently degrading to open-room editor mode (the dangerous default — a corrupted encrypted link must never quietly drop you into an unauthenticated editable room); a valid fragment returns the capability. The attacker-controlled kdf iteration field is also range-clamped on decode, so a hand-edited link can't force a weaker-than-legacy key derivation.

Why did the inline page scripts get moved into separate module files?

They were collateral of tightening the Content-Security-Policy. The old policy allowed script-src 'self' 'unsafe-inline', which permits any injected inline <script> to run — the exact thing you don't want in an app that interpolates peer-supplied data into the DOM. Dropping 'unsafe-inline' means inline <script> blocks no longer execute, so the landing-page and board-history bootstraps moved into real ES modules (index-home.js, boards-home.js) loaded with <script type="module" src=...>. The CSP also gained base-uri 'none' and form-action 'self' to close <base>-tag and form-hijack vectors.

Why ECDSA P-256 instead of Ed25519?

Ed25519 is smaller and more modern, but Web Crypto support for it only shipped in very recent browser versions and throws "Unrecognized name" on most installed browsers. ECDSA P-256 has been supported everywhere crypto.subtle exists for years. For a tool people open in whatever browser they already have, universal support matters far more than Ed25519's marginal size advantage.

Is the relay really in the dark, even about who's drawing?

In an encrypted room, yes. Every frame — document updates, snapshots, cursor positions, names, the live drawing preview — is AES-256-GCM-encrypted before it leaves the browser, and the PartyKit relay only ever forwards opaque bytes. The one thing peers do advertise in the clear is an "encrypted room" marker, so a visitor who arrives without a key knows to ask for an invite link rather than silently joining an unreadable room.

Can I use this offline?

Yes. All drawing data is persisted to IndexedDB via y-indexeddb. If you lose your connection, you can keep drawing normally. When you reconnect, Y.js automatically merges your offline changes with any changes made by other users while you were away. The CRDT model guarantees this merge is conflict-free.

Why PartyKit instead of a custom WebSocket server?

PartyKit provides a Cloudflare Workers-based WebSocket runtime with built-in room isolation, auto-scaling, and global edge deployment. The server code is just 35 lines — accept connections and broadcast messages. PartyKit handles all the infrastructure complexity (SSL, connection management, scaling) so I can focus on the client-side logic.

What's the "Board History" feature?

The boards page (boards.html) shows all rooms you've previously visited, stored in localStorage. Each entry tracks your role (owner/collaborator/viewer), whether the room is encrypted, when you last accessed it, and how many times. This makes it easy to return to a room without bookmarking the URL.

How is the canvas performance with many shapes?

The drawing engine redraws via requestAnimationFrame and only renders shapes inside the current viewport. Two things keep the hot paths cheap on larger boards: a spatial shape index (buildShapeIndex in draw-geometry.js) avoids repeated O(n) array scans when resolving hit-tests and connector endpoints, and connector geometry is derived only for connectors actually being drawn rather than recomputed for every shape. For typical whiteboard usage (dozens to low hundreds of shapes) interaction stays smooth; very large boards could still benefit from canvas layering, which hasn't been necessary in practice.

Can I export or save a board as an image?

Yes. The Save action opens an interactive export modal that renders the board to an off-screen canvas and lets you pan and zoom to frame exactly what you want. From there you can save a PNG (rendered at 2× for retina sharpness via the canvas toDataURL API) or a single-page PDF (the same canvas snapshot placed into a jsPDF document sized to match). The export uses a separate render pass, so what you save is independent of your current on-screen zoom and pan.

How do connectors stay attached when I move a shape?

A connector stores the IDs of the two shapes it links (fromId/toId), not fixed coordinates. The endpoints are recomputed every frame from the live bounding boxes of those shapes, picking the nearest pair of edge anchors. So when any peer moves a connected shape, the CRDT update changes that shape's position and the connector re-routes on the next render with no extra bookkeeping. If a linked shape is deleted, the now-dangling connector is detected and cleaned up.

Technology Stack

Core Technologies

Category	Technology	Version	Purpose
Language	JavaScript (ES Modules)	ES2022+	Vanilla JS — no framework overhead for a canvas-heavy app
Server	TypeScript	—	PartyKit server type safety
Rendering	HTML5 Canvas	—	High-performance 2D drawing surface
Sync Engine	Y.js	^13.6.0	CRDT library for conflict-free real-time collaboration
Real-time	PartyKit	^0.0.115	WebSocket server for message relay
Build Tool	Vite	^8.0.16	Fast dev server and production bundler
Tests	Vitest	^4.1.8	Unit tests over crypto, KDF, protocol, sync, snapshot, geometry, text-wrap, and link logic
Export	jsPDF	^4.2.1	Generate a single-page PDF from a rendered canvas snapshot

Frontend

Framework: None (Vanilla JavaScript with ES Modules)
Rendering: HTML5 Canvas API for whiteboard, DOM for UI
State Management: Y.js shared types (Y.Map, Y.Array) as the single source of truth
Styling: Custom CSS3 with CSS variables, Inter font from Google Fonts
Build Tool: Vite in MPA (Multi-Page Application) mode

Backend

Runtime: PartyKit (Cloudflare Workers-based)
Server: ~35-line WebSocket broadcast relay (party/index.ts) — no app logic, no trust
API Style: Typed binary protocol — signed {epoch, update, sig} envelopes + snapshots for doc sync; standard awareness for presence
Authorization: Capability links (owner/editor/viewer) enforced by ECDSA P-256 signatures verified peer-side, rooted in a per-room owner key
Encryption: E2E AES-256-GCM — server never sees plaintext

Infrastructure

Hosting: Vercel (static site) + PartyKit (WebSocket relay)
CI/CD: GitHub Actions — every PR/push to main runs Vitest + the Vite build; the PartyKit relay deploys on push to main, path-filtered to server changes and gated behind that same job. The Vercel frontend auto-deploys from Git.
URL Routing: Vercel rewrites (/room/:id → room.html)
Security headers: strict Content-Security-Policy in vercel.json — script-src 'self' only (no unsafe-inline; all page scripts are real ES modules), base-uri 'none', form-action 'self', frame-ancestors 'none', plus HSTS, Referrer-Policy: no-referrer, and a locked-down Permissions-Policy. Google Fonts is the only cross-origin allow-list.
Caching: Immutable caching for JS bundles, must-revalidate for HTML

Development Tools

Package Manager: npm
Bundler: Vite (Rollup-based production builds)
Dev Server: Vite dev server with custom middleware for room routing
Testing: Vitest (npm test) — unit tests across the crypto, key-derivation, certificate, protocol, signed-sync, snapshot-store, color/shape sanitization, capability-link, draw/connector geometry, text-wrap, laser-trail, and keyboard-intent modules. Logic is deliberately factored into pure, browser-free modules so it can be tested without a DOM.
Image Generation: Sharp (for favicon/icon generation via scripts/generate-icons.js)
Concurrent Dev: concurrently (run Vite + PartyKit dev servers together)

Key Dependencies

Package	Purpose
`yjs`	CRDT document model — Y.Map for boards, Y.Array for shapes
`y-indexeddb`	Persist Y.Doc to browser IndexedDB for offline support
`y-partykit`	PartyKit integration helpers for Y.js
`y-protocols`	Awareness (presence) wire protocol; doc sync is a custom signed layer
`partykit`	Server runtime for the WebSocket relay
`partysocket`	Client-side WebSocket with auto-reconnect for PartyKit
`lib0`	Binary encoding/decoding — used to frame the signed update envelopes
`jspdf`	Render the chosen canvas view into a downloadable single-page PDF
`vite`	Build tool and dev server
`vitest`	Test runner for the crypto, protocol, and sync units
`concurrently`	Run Vite + PartyKit dev servers in parallel
`sharp`	Image processing for favicon generation

Cryptography Stack

Component	Technology	Configuration
Key Derivation	PBKDF2	600,000 iterations (SHA-256) for new rooms; the count travels in the capability link's `kdf` field, clamped to `[100k legacy, 5M]` on decode so a tampered link can't downgrade below the legacy floor or pin a victim to a multi-second derivation. Pre-hardening links fall back to 100,000.
Encryption (confidentiality)	AES-256-GCM	Authenticated encryption with 12-byte random IV
Salt	Random per-room, carried in link	16 random bytes minted per room and embedded in the capability link, so the same password no longer maps to a precomputable key (the room ID alone is public). Pre-salt links fall back to the legacy `whiteboard-{roomId}` salt.
Signing (authorization)	ECDSA P-256 / SHA-256	Raw r‖s (64-byte) signatures over `epoch ‖ update`; chosen over Ed25519 for universal Web Crypto support
Owner certificates	ECDSA P-256 over canonical JSON	Owner key signs `{room, epoch, editorPub}` to vouch for each epoch's editor key
API	Web Crypto API	Hardware-accelerated, browser-native; non-extractable verify keys

Browser Requirements

WebSocket API
IndexedDB
Web Crypto API (crypto.subtle)
TextEncoder/TextDecoder
HTML5 Canvas
ES Modules (type="module")

Architecture Overview

System Diagram

flowchart TD
    subgraph Browser["Browser (Client)"]
        LP[Landing Page<br>index.html]
        BP[Boards Page<br>boards.html]
        RP[Room Page<br>room.html]

        subgraph AppCore["Application Core"]
            APP[app.js<br>Entry Point]
            DRW[drawing.js<br>Canvas Rendering]
            BRD[boards.js<br>Board Manager]
            AWR[awareness.js<br>User Presence]
            UND[undo-redo.js<br>History Manager]
            MOD[modal.js<br>Dialog System]
            RM[room-manager.js<br>Room & Auth]
        end

        subgraph SyncLayer["Sync Layer"]
            YJS[yjs-setup.js<br>Y.Doc Init + Rotation]
            SDS[signed-doc-sync.js<br>Signed Update Sync]
            PROTO[protocol.js<br>Envelope + Signing]
            SP[sync-provider.js<br>WebSocket Transport]
            CRY[crypto.js<br>AES-GCM + ECDSA]
            CERT[room-cert.js<br>Epoch Certificates]
            SNAP[snapshot-store.js<br>Per-Epoch Snapshot Cache]
        end

        subgraph Storage["Local Storage"]
            IDB[(IndexedDB<br>y-indexeddb)]
            LS[(localStorage<br>Board History)]
        end
    end

    subgraph Server["PartyKit Server"]
        PK[party/index.ts<br>Message Relay]
    end

    LP --> RP
    BP --> RP
    RP --> APP
    APP --> DRW
    APP --> BRD
    APP --> AWR
    APP --> UND
    APP --> MOD
    APP --> RM

    APP --> YJS
    YJS --> SDS
    SDS --> PROTO
    SDS --> CERT
    PROTO --> CRY
    SDS --> SP
    SDS --> SNAP
    SP --> CRY
    SNAP --> LS
    YJS --> IDB

    SP <-->|WebSocket<br>Ciphertext / Plain| PK
    PK <-->|Broadcast to<br>Other Clients| SP

    RM --> CRY
    RM --> LS
    APP --> LS

    DRW --> AWR
    BRD --> AWR

Data Flow Diagram

sequenceDiagram
    participant User
    participant Canvas as drawing.js
    participant YDoc as Y.js Document
    participant IDB as IndexedDB
    participant Signed as signed-doc-sync.js
    participant Provider as sync-provider.js
    participant Server as PartyKit
    participant Peer as Remote Peer

    User->>Canvas: Draw shape
    Canvas->>YDoc: Append to Y.Array
    YDoc->>IDB: Persist locally
    YDoc->>Signed: Local update event

    alt Encrypted Room (editor)
        Signed->>Signed: Sign epoch‖update (ECDSA P-256)
        Signed->>Provider: envelope { epoch, update, sig }
    else Open Room
        Signed->>Provider: envelope { epoch:0, update }
    end

    alt Encrypted Room
        Provider->>Provider: AES-256-GCM encrypt
    end
    Provider->>Server: Send via WebSocket
    Server->>Peer: Broadcast to others

    Note over Peer: viewers can decrypt but<br>cannot produce a valid sig

    alt Encrypted Room
        Peer->>Peer: Decrypt, verify cert + signature
        Peer-->>Peer: Drop if wrong epoch / bad sig
    end

    Peer->>YDoc: Apply verified update (CRDT merge)
    YDoc->>Canvas: Observer triggers redraw

Component Descriptions

app.js — Main Entry Point

Purpose: Orchestrates initialization and wires all modules together
Location: js/app.js
Key responsibilities: Tool switching with per-tool settings persistence, keyboard shortcuts, zoom/pan controls, side panel management, canvas resizing, browser compatibility checks, global error handling

drawing.js — Canvas Rendering Engine

Purpose: Handles all HTML5 Canvas drawing, hit-testing, shape manipulation, and live drawing previews
Location: js/drawing.js
Key responsibilities: Rendering every tool from Y.Array data (freehand/highlighter, line/arrow, rect/circle/ellipse/diamond/triangle, text, sticky notes, connectors), mouse/touch interaction handling, shape selection (single and multi-select), move/resize operations, copy/paste/duplicate, sticky-note text scrolling, relationship-bound connector creation and re-routing, the ephemeral laser-pointer trail, read-only mode enforcement, remote cursor rendering, and an off-screen renderBoardToCanvas pass used by the PNG/PDF export

draw-geometry.js, connector-geometry.js, text-wrap.js — Pure Geometry & Layout

Purpose: Browser-free math extracted from the canvas engine so it can be unit-tested without a DOM
Location: js/draw-geometry.js, js/connector-geometry.js, js/text-wrap.js
Key responsibilities: draw-geometry.js — hit-testing, polygon point generation for diamonds/triangles, arrowhead points, dash patterns, degenerate-shape detection, and a spatial shape index that avoids O(n) scans. connector-geometry.js — resolving a connector's endpoints to the nearest edge anchors of its two bound shapes, and finding dangling connectors whose targets were deleted. text-wrap.js — word-wrap and scroll-extent math shared by the text tool and sticky notes.

laser-trail.js — Ephemeral Pointer Trail

Purpose: The laser-pointer presence effect that is never persisted as a shape
Location: js/laser-trail.js
Key responsibilities: Prune trail points older than a fixed age so the laser fades; broadcast over awareness (presence), never written to the Y.Array. safeToolName deliberately rejects laser so it can't be smuggled in as a stored shape.

keyboard-intent.js — Shortcut Intent

Purpose: Pure decisions about keyboard handling, kept out of app.js so they're testable and never preventDefault a no-op
Location: js/keyboard-intent.js
Key responsibilities: Decide whether a Delete/Backspace keypress should consume the event and delete the selection (only when not read-only and something is selected).

yjs-setup.js — Y.js Initialization & Rotation

Purpose: Wires the Y.Doc to local persistence, the WebSocket transport, and the signed sync layer, and drives owner-only room rotation
Location: js/yjs-setup.js
Key responsibilities: Y.Doc creation, IndexedDB persistence, AES key derivation from the room password, building the SignedDocSync from the URL capability (signed for encrypted rooms, open/unsigned for password-free rooms), a snapshot relay cache keyed by room+epoch, one-time migration of pre-encryption data, and rotateRoom() which mints a new epoch and reloads the owner into the fresh link. Deliberately does not eagerly create the default board (it's created lazily on first write to avoid a Y.Map conflict between joiners).

signed-doc-sync.js — Signed Update Sync

Purpose: Binds a Y.Doc to the transport and enforces the edit/view-only boundary cryptographically
Location: js/signed-doc-sync.js
Key responsibilities: Two modes — signed (capability rooms: only editor-signed, current-epoch, cert-valid updates and snapshots are ever applied; viewers can't author) and open (password-free rooms: unsigned, everyone edits). Verifies the owner-signed epoch certificate once on start and fails closed if it doesn't pin the editor key. Signs and broadcasts local editor updates, answers snapshot bootstrap requests, persists/relays the latest verified snapshot, and handles owner-signed rotation notices by marking the epoch superseded.

protocol.js — Wire Protocol

Purpose: Defines the binary message format and the bytes that get signed
Location: js/protocol.js
Key responsibilities: Message type constants (UPDATE / SNAPSHOT / SNAPSHOT_REQUEST / AWARENESS / ROTATE), encodeEnvelope/decodeEnvelope (epoch ‖ update ‖ signature via lib0), and signUpdate/verifyUpdate which sign the update prefixed by its epoch so a signature from one epoch can't be replayed in another.

room-cert.js — Epoch Certificates

Purpose: The owner root-of-trust primitive that makes the editor key trustworthy
Location: js/room-cert.js
Key responsibilities: mintCert — the owner key signs a statement binding {room, epoch, editorPub}; verifyCert — checks a cert against the owner public key and returns the bound epoch/editor key or null (rejecting anything not owner-signed, malformed, or tampered, never throwing).

snapshot-store.js — Per-Epoch Snapshot Cache

Purpose: A localStorage-backed cache of the latest signed full-state snapshot, used to bootstrap a freshly joined or reconnecting peer without waiting on a live editor
Location: js/snapshot-store.js
Key responsibilities: Read/write a snapshot keyed by room + epoch (base64 in localStorage), and prune snapshots from superseded epochs on construction so rotated rooms don't accumulate stale blobs. The primary document store stays in IndexedDB; this is only a relay-bootstrap cache. pruneOldSnapshots is written pure over a Storage-like object so it's unit-testable without a browser.

sync-provider.js — WebSocket Transport

Purpose: The PartyKit WebSocket transport that carries typed, optionally-encrypted messages and user presence
Location: js/sync-provider.js
Key responsibilities: WebSocket connection management with auto-reconnect, a typed message channel consumed by the signed sync layer (onMessage/onConnect), AES-256-GCM encrypt/decrypt wrapping of all frames in encrypted rooms (silently dropping frames it can't decrypt rather than erroring), awareness for presence (including an enc flag so keyless visitors know to ask for an invite link), and re-broadcasting awareness when a new peer appears.

awareness.js — User Presence

Purpose: Manages ephemeral user state (cursors, names, colors, active board, in-progress drawings)
Location: js/awareness.js
Key responsibilities: Local user state broadcasting, remote cursor rendering with labels, user list UI, live drawing preview propagation, throttled cursor updates to reduce network traffic

boards.js — Multi-Board Manager

Purpose: Manages multiple boards (whiteboards) within a single room
Location: js/boards.js
Key responsibilities: Board creation and switching, board tab UI rendering, board clearing, awareness sync of current board per user

crypto.js — Confidentiality + Authorization Primitives

Purpose: All Web Crypto usage — both the encryption layer and the signing layer
Location: js/crypto.js
Key responsibilities: AES-256-GCM authenticated encryption with PBKDF2 key derivation (600K iterations for new rooms, SHA-256, random per-room salt — both the count and salt are caller-supplied from the capability link, with a legacy 100K / room-ID-salt fallback for pre-hardening links) and random IV per message; ECDSA P-256 keypair generation, export/import (raw public, PKCS8 private), raw signData/verifyData (64-byte r‖s, never throws), and signStatement/verifyStatement over a canonical JSON serialization for certs and rotation notices.

room-manager.js — Capabilities & Access Control

Purpose: Encodes and decodes the capability links that grant owner / editor / viewer access
Location: js/room-manager.js
Key responsibilities: Minting a fresh owner capability (owner root key + first editor key + epoch-1 cert, plus a random per-room PBKDF2 salt and iteration count), encoding role-scoped links (owner carries both private keys, editor carries the editor key, viewer carries no private key), strict v3 token decode that downgrades any claimed role lacking the matching key and clamps the attacker-supplied kdf count to [legacy, max], fail-closed hash parsing (parseCapabilityHash throws on a tampered/truncated link rather than silently dropping into open-room editor mode), owner-only rotateCapability (new epoch + editor key + cert), and shareable-link generation that never emits an owner link.

undo-redo.js — History Manager

Purpose: CRDT-aware undo/redo using Y.js UndoManager
Location: js/undo-redo.js
Key responsibilities: Only tracks local user's changes (never undoes other users' work), 500ms grouping window for rapid changes, stack state notifications for UI updates

modal.js — Dialog System

Purpose: Custom modal system replacing native browser dialogs
Location: js/modal.js
Key responsibilities: Prompt, confirm, alert dialogs, invite modal, password modal, keyboard shortcuts help, text extraction modal

board-history.js — Board History Manager

Purpose: Persists room visit history in localStorage
Location: js/board-history.js
Key responsibilities: Save/load board history, role tracking (owner/collaborator/viewer) with owner preservation, access counting, relative time formatting

config.js — Configuration Constants

Purpose: Centralizes all magic numbers and configurable values
Location: js/config.js
Key responsibilities: Zoom limits, timing intervals, crypto parameters, drawing defaults, user color palette

party/index.ts — PartyKit Server

Purpose: Minimal WebSocket message relay
Location: party/index.ts
Key responsibilities: Accept WebSocket connections, broadcast messages to all other clients in the room (never echoes back to sender). Only 35 lines — all logic lives client-side.

External Integrations

Service	Purpose	Notes
PartyKit	WebSocket broadcast relay for real-time sync	Dumb relay — only ever sees ciphertext in encrypted rooms
Vercel	Static site hosting with URL rewrites and CSP	Auto-deploys the frontend on push to `main`
GitHub Actions	CI (Vitest + Vite build) and PartyKit auto-deploy	Relay deploy is path-filtered and gated behind the test+build job
Google Fonts	Inter typeface for UI	Allow-listed in the Vercel CSP

Key Architectural Decisions

CRDTs over Operational Transform

Context: Needed conflict-free real-time collaboration without a central authority
Decision: Y.js CRDT library
Rationale: CRDTs guarantee eventual consistency without a server. Unlike OT (used by Google Docs), CRDTs work offline and don't need a central server to resolve conflicts. Y.js is the most mature CRDT implementation for JavaScript.

PartyKit over Raw WebRTC

Context: Originally used y-webrtc for peer-to-peer connections, but WebRTC has NAT traversal issues
Decision: Migrated to PartyKit WebSocket relay
Rationale: PartyKit provides reliable message delivery without NAT/firewall issues. The server is a simple broadcast relay (doesn't see decrypted data), maintaining the privacy model while improving reliability.

Client-Side Encryption (confidentiality)

Context: Wanted true E2E encryption where the relay server never sees plaintext
Decision: AES-256-GCM encryption with PBKDF2 key derivation, all in the browser
Rationale: The Web Crypto API provides hardware-accelerated crypto. By encrypting every frame before sending, the PartyKit server only ever sees ciphertext. Password-derived keys mean no key-exchange protocol is needed — users share the password (embedded in the invite link) out of band.

Signature-enforced view-only over a client-side flag (authorization)

Context: Encryption hides content from the server, but everyone with the password can still decrypt — so a "view-only" link that only sets a client flag is trivially bypassed by editing the URL or the JS. View-only had to survive a hostile viewer.
Options: Trust a client-side readOnly flag, run a server-side auth check (breaks the dumb-relay/P2P model), or sign every edit so unauthorized writes are rejected by peers.
Decision: Editors sign each update with a per-epoch ECDSA P-256 key; every peer verifies before applying, and viewers are simply never given a signing key.
Rationale: Enforcement moves from convention to cryptography. A viewer can decrypt and render, but any update they emit fails verification at every honest peer, so it never lands in the shared document. No server and no accounts required.

Owner root-of-trust with epoch certificates (revocation)

Context: If the editor key is just embedded in links, there's no way to revoke a leaked link or distinguish "can edit" from "controls the room" — and in a serverless system there's no authority to ask.
Options: A single shared editor key (no revocation), a server-issued token (breaks P2P), or a two-tier PKI rooted in an owner key.
Decision: A per-room owner ECDSA keypair is the root of trust. The owner signs an epoch certificate binding the current editor public key to an epoch number; peers only trust an editor key that a valid owner cert vouches for. Only the owner holds the owner private key, so only the owner can mint a new epoch.
Rationale: Rotation becomes "owner mints epoch N+1 with a fresh editor key and broadcasts an owner-signed rotate notice." Peers supersede the old epoch and stop applying its updates; anyone holding an old link can no longer sign valid edits. This is real revocation with no central server — see room-cert.js and signed-doc-sync.js.

ECDSA P-256 over Ed25519

Context: Needed a signing algorithm available in the browser's Web Crypto API across the installed base, not just the latest releases.
Options: Ed25519 (smaller, modern) or ECDSA P-256 (older, ubiquitous).
Decision: ECDSA P-256.
Rationale: Web Crypto Ed25519 only shipped in very recent browser versions and throws "Unrecognized name" on most installed browsers. ECDSA P-256 has been supported for years everywhere crypto.subtle exists, which matters far more than Ed25519's marginal size advantage for a tool people open in whatever browser they already have.

Custom signed-update sync over Y.js's stock doc-sync protocol

Context: The view-only and rotation guarantees require inspecting, signing, and verifying every update — but y-protocols' doc sync is opaque about which bytes are "an authored edit."
Options: Keep y-protocols doc sync and try to bolt auth on around it, or replace just the document-sync layer with a thin custom protocol while keeping Y.js's CRDT core and the awareness protocol.
Decision: A small custom layer (signed-doc-sync.js + protocol.js) that exchanges signed {epoch, update, sig} envelopes and full-state snapshots for bootstrap; awareness still rides the standard channel.
Rationale: Owning the doc-sync envelope is what makes per-update signing, epoch tagging (replay protection), and fail-closed verification possible. Y.js still does all the conflict resolution and offline merging — only the transport framing is custom.

Strict CSP + allow-list sanitization over ad-hoc escaping (XSS)

Context: The untrusted input in a P2P whiteboard is the shared document itself — peer-supplied shape fields, names, and presence state, several of which get interpolated into innerHTML. Per-call escaping is easy to forget, and three modules had in fact drifted into separate escapeHtml copies (one missing quote-escaping).
Options: Keep hand-escaping at each sink, or layer a centralized sanitization API behind a CSP that fails safe if a sink is ever missed.
Decision: A single shared escapeHtml plus type-narrowing allow-list helpers (safeColor for #hex only, safeNumber, safeToolName, and sanitizeShape in shape-schema.js), behind a script-src 'self' CSP (no unsafe-inline, plus base-uri 'none' / form-action 'self').
Rationale: The sanitizers reject anything outside the narrow set of values the app actually produces, so injected markup collapses to an inert fallback rather than executing. The CSP is the backstop — a missed sink still can't run an injected script — and dropping 'unsafe-inline' forced the previously inline page bootstraps into real modules (index-home.js, boards-home.js).

Multi-Page Application (MPA) over SPA

Context: The app has three distinct pages (landing, boards list, whiteboard room)
Decision: Vite MPA mode with separate HTML entry points
Rationale: Each page has very different functionality. MPA keeps bundles small (the landing page doesn't load Y.js), and Vite's MPA support handles the routing cleanly. URL rewrites in Vercel handle the /room/:id pattern.

IndexedDB for Local Persistence

Context: Users need to return to their whiteboards even without network
Decision: y-indexeddb for Y.Doc persistence, localStorage for board history
Rationale: IndexedDB handles the potentially large binary Y.Doc state, while localStorage is simpler for the small structured board history data. y-indexeddb integrates directly with Y.js for seamless offline support.

Back to All Projects