Platform architecture

Overview

Blincr is a real-time co-browsing platform built on Cloudflare Workers. It lets users share their browsing sessions as audit trails that others can follow live or replay later. The platform consists of three deployable units: a Cloudflare Worker (backend + SSR frontend), a Chrome extension (event capture and trail management), and a Durable Object (real-time session coordination).

Component map

+-------------------------+       +----------------------------+
|   Chrome Extension      |       |   mit-blincr-com Worker    |
|                         |       |                            |
|  content.ts             |       |  workers/app.ts            |
|    click, scroll,       | WSS   |    React Router SSR        |
|    selection, clipboard +------>+    /api/auth/*              |
|                         |       |    /api/auth/passkey/*      |
|  background.ts          | HTTP  |    /api/user/trails/*       |
|    session management   +------>+    /api/trails/*            |
|    trail recording      |       |    /api/audit/*             |
|    replay engine        |       |    /api/sessions            |
|                         |       |                            |
|  sidepanel.ts           |       |  SessionCoordinator (DO)   |
|    live view + library  |       |    WebSocket hub            |
|                         |       |    trail state              |
|  popup.ts               |       |    audit logging            |
|    session + trails tab |       |                            |
+-------------------------+       +----------------------------+
                                         |          |
                                    +----+     +----+
                                    |          |
                               D1 (AUDIT_DB)  R2 (SESSION_SNAPSHOTS)

Data flow

1. Session start — Extension calls POST /session/ which creates a Durable Object instance. The extension opens a WebSocket to the DO.
2. Event capture — Content script captures navigation, click, scroll, selection, clipboard, page_info, and overlay events. Each event is sent via chrome.runtime.sendMessage to the background script.
3. Event relay — Background script wraps the event with a timestamp and participant ID, pushes it to the local trail array, then sends it over the WebSocket to the DO.
4. Broadcast — The DO broadcasts each event to all connected WebSocket clients (viewers). Viewers replay the events in their browser using the content script's replay functions — including overlay events which render/update/remove persistent UI components (comments).
5. Overlay persistence — On page load or SPA navigation, the content script asks the background for materialized overlay state (GET_OVERLAYS). Background scans the trail for overlay events matching the URL, applies CRUD in order, and returns live instances. Comments and future overlay plugins reappear on revisited pages and during trail replay.
6. Session stop — The trail is auto-saved to IndexedDB locally. The DO persists the trail to R2 as a JSON snapshot.

Storage layers

• D1 (AUDIT_DB) — Relational storage for users, sessions, cloud trails, passkey credentials, and the audit log.
• R2 (SESSION_SNAPSHOTS) — Object storage for full trail JSON snapshots (keyed by session ID and user trail ID).
• IndexedDB (blincr-trails) — Browser-local storage in the extension for offline trail management, folders, and search.
• Durable Object storage — Transient session state (participants, current trail, current URL).

Deployment

The Worker is deployed as mit-blincr-com on Cloudflare with:

• Compatibility date: 2025-06-01
• Compatibility flags: nodejs_compat
• Assets: Vite-built React Router client in dist/client
• D1 binding: AUDIT_DB -> mit-blincr-db
• R2 binding: SESSION_SNAPSHOTS -> blincr-session-snapshots
• DO binding: SESSION_COORDINATOR -> SessionCoordinator class

The extension is built separately with esbuild and loaded as an unpacked Chrome extension during development.