How the pieces fit together.

Architecture

A TypeScript modular monolith: a React 19 + Vite single-page app (public pages prerendered to static HTML), an Express 5 + Socket.IO 4 server, PostgreSQL via Prisma, and a shared package containing Zod schemas and the pure game engines used by the server.

Identity

POST /api/session issues a random 256-bit bearer token; the database stores only its SHA-256. The token authenticates REST calls and the Socket.IO handshake. Clients never send their own role or participant id — the server derives it from the authenticated session.

Rooms

Rooms are WATCH or GAME (with a fixed game type) and that never changes. Participants are unique per (room, role) with only two roles, so a third participant is impossible even under concurrent joins. Room codes have 40 bits of entropy and are rate limited; invite links add a 128-bit key.

Watch Together

• Capability check for HTMLMediaElement.captureStream() (or Firefox’s mozCaptureStream()) and RTCPeerConnection.
• The creator is always the offerer, with four fixed transceivers: movie video, movie audio, camera and microphone. Toggling devices uses replaceTrack, so no renegotiation is needed.
• The server keeps an authoritative playback state with a sequence number; the creator’s element follows it and reports its real position every second; drift over 1 s is corrected.
• Readiness: the guest is ready while frames keep arriving; the creator while its element can play. Unready for more than 2.5 s (or offline for 4 s) pauses both; recovery resumes from the paused position.

Games

Every engine implements init / apply / outcome / view as pure functions. Actions carry an id and the expected state version; stale versions and replayed ids are rejected. State is persisted after every accepted action with an optimistic version check, and each player receives a seat-specific view (trivia answers stay hidden until the reveal).

Quick Share

• Link states: AVAILABLE → RESERVED → TRANSFERRING → CONSUMED, plus EXPIRED and CANCELLED.
• Reservation is one conditional SQL UPDATE; PostgreSQL row locking guarantees exactly one winner among concurrent recipients.
• The reservation returns a secret token with a 45-second lease renewed during transfer. Resuming requires that token.
• Chunks (64 KiB by default) are sent with bufferedAmountLowThreshold backpressure. The receiver writes to the Origin Private File System when available and verifies SHA-256 incrementally.
• Completion is another conditional UPDATE that also checks the hash and size against the sender’s declaration.

Security controls

• Strict Content Security Policy, HSTS (behind HTTPS), frame-ancestors none, restricted Permissions-Policy.
• CORS limited to configured origins; Zod validation of every request body and socket event; payload size limits.
• Per-IP HTTP rate limits (stricter for joining rooms and creating links) and a per-socket event token bucket.
• Secrets are never logged; tokens, SDP and ICE candidates are redacted from logs.
• Short-lived TURN credentials (coturn shared-secret scheme) minted per guest.

Scaling

Live coordination (socket membership, playback timers, per-room locks) is held in memory in one process. Running several instances requires the Socket.IO Redis adapter, sticky sessions and moving locks/timers to shared storage.