SceneVault developer docs

Your Excalidraw drawings keep ending up in a folder called Downloads. SceneVault gives them a real home: a tidy, searchable library where every scene autosaves to the cloud and the full editor is one click away.

It is a single Next.js App Router application that stitches together four services: Better Auth for authentication, Convex as a reactive metadata database, Cloudflare R2 for scene-bundle storage, and the embedded @excalidraw/excalidraw editor. The guiding principle is a clean split: scene metadata (titles, folders, versions, object keys, content hashes) lives in Convex and is strongly consistent and reactive; the heavy scene bundles live in R2 and are accessed only through short-lived presigned URLs that never touch the Next.js server.

The fastest way to try SceneVault is local demo mode, which needs no Better Auth, Convex, or R2 credentials. Scenes are stored in your browser's localStorage.

# 1. Install dependencies
pnpm install

# 2. Run in local demo mode (no external services)
NEXT_PUBLIC_LOCAL_DATA=1 pnpm dev

# 3. Open the dashboard
open http://localhost:3000/dashboard

Ready to wire up real services and persist scenes across devices? Jump to Production setup.

Everything you need to keep a growing pile of drawings calm, searchable, and saved.

A small, modern stack where each service owns one job. Convex holds reactive metadata; R2 holds bytes; Better Auth holds identity.

The browser talks to three planes: Convex for live metadata, Next.js route handlers for presigned storage access, and R2 directly for the actual scene bytes.

The split is deliberate. Convex is the control plane — small, reactive, strongly consistent rows that every client subscribes to. R2 is the data plane — large, opaque blobs the server never reads on the hot path. The Next.js route handlers are a thin brokerage layer: they authorise a request, then hand the browser a presigned URL so the bytes flow browser ↔ R2 directly. That keeps multi-megabyte scene payloads off both the database and the serverless function.

Three flows carry every byte in the app. Each keeps large payloads off the database and routes them browser-to-R2 over short-lived presigned URLs.

All metadata lives in Convex, profile-scoped and indexed for the exact access patterns the app needs. Eight tables, no joins on the hot path.

Indexes mirror the queries exactly. The dashboard's getLibrary reads folders by by_profile and scenes by by_profile_updated in parallel; share lookups hit the unique by_token index; and every collab read is a single by_scene or by_room_session scan.

Scene bundles and thumbnails are stored as objects in a Cloudflare R2 bucket under a deterministic, profile-scoped key layout.

users/{profileId}/scenes/{sceneId}/head/excalidraw.json   # scene bundle
users/{profileId}/scenes/{sceneId}/head/thumbnail.png     # PNG preview

Browsers never receive long-lived credentials. Every read and write goes through a presigned URL minted server-side with a 5-minute (300s) expiry, scoped to one exact object key and HTTP method. Because the key is derived from profileId + sceneId rather than supplied by the client, and the commit mutations recompute and re-check it, a client can never read or write outside its own namespace.

Object operations are kept simple and idempotent. Deletes remove the bundle and thumbnail unconditionally (a no-op if absent), and the duplicate flow uses a server-side R2 CopyObjectso a shared scene's bytes are cloned without round-tripping through the browser.

Two stores, two consistency guarantees, one source of truth. Convex is authoritative for which bytes are current; R2 merely holds them.

A save is effectively two phases: upload bytes, then commit the pointer. If the second phase is lost, the uploaded bytes are simply never referenced — the next save overwrites the same head key — and no reader is ever exposed to them. Identical content short-circuits the commit entirely via the content hash, so the version counter only ever moves forward on a real change.

Live convergence: per-element LWW

In a live room each element converges independently. The server applies the same tie-break Excalidraw uses on the client: a higher version wins; on a tie the lower versionNonce wins; identical means no change. Mirroring reconcileElements keeps server and clients convergent, and deletes propagate as tombstones that the sweep cron later garbage-collects.

export function incomingElementWins(incoming, stored) {
  if (!stored) return true;
  if (incoming.version !== stored.version)
    return incoming.version > stored.version;        // higher version wins
  if (incoming.versionNonce !== stored.versionNonce)
    return incoming.versionNonce < stored.versionNonce; // tie: lower nonce wins
  return false;                                       // identical: no change
}

Authorization is enforced three times, independently, on every storage request — defence in depth so no single bug opens a door.

const protectedPrefixes = ["/dashboard", "/scenes", "/api/scenes"];

export default function proxy(req: NextRequest) {
  if (process.env.NEXT_PUBLIC_LOCAL_DATA === "1") return;
  const signedIn = req.cookies
    .getAll()
    .some((cookie) => cookie.name.includes("session_token"));
  if (isProtectedPath(req.nextUrl.pathname) && !signedIn) {
    return NextResponse.redirect(new URL("/sign-in", req.url));
  }
});

Beyond the three layers: presigned URLs are scoped to a single key and expire in five minutes; share tokens are 24 random bytes looked up by a unique index and can be disabled or rotated instantly; and collab session secrets are stored only as SHA-256 hashes, so a database leak can't be replayed to spoof a session.

Any scene can be shared with a per-scene, per-mode token — view or edit — without exposing your account.

Tokens are 24 random bytes of hex, stored in the sceneShares table and looked up by a unique index. Owners can rotate a token (invalidating the old link instantly) or toggle enabled to revoke access without deleting the link. A disabled or unknown token resolves to null, so guests simply see “not found.”

Anonymous guests can load the scene and join live editing with an edit token, but durable R2 persistence still requires sign-in: the upload, commit, thumbnail-upload, and duplicate routes demand a Better Auth session. A guest who duplicates a shared scene gets a fresh copy under their ownprofile namespace. The token grants entry to the room; it never grants direct write access to someone else's storage.

Start a real-time room on any scene and edit together. The live working set lives in Convex so a browser crash can never lose edits.

Room lifecycle

Only the scene's profile can startRoom. The room then moves through four states as the first joiner seeds it from the durable R2 snapshot:

Joining issues a session: joinRoom returns a one-time secret (only its hash is stored) and a presence row. Edits are diffed against last-known versions, debounced, and pushed in batches; the server reconciles each element with last-write-wins. Cursors and selections stream as throttled presence updates, denormalised so a single index read renders every collaborator.

Snapshots & garbage collection

Among active signed-in sessions, exactly one is elected snapshotter — the lexicographically lowest session id, so the choice is deterministic and needs no coordination. It debounces the live set back to R2 and calls markRoomSnapshot with a watermark. A room is “dirty” whenever a live element is newer than that watermark, and the sweep cron never collects a dirty room — the guarantee that no edit is lost even if every browser disconnects before snapshotting. Guests can never snapshot; persistence always requires a signed-in session.

Timings & caps

Rate limiting

Public, token-gated mutations are throttled by a per-session token-bucket limiter persisted in collabRateLimits, isolated to its own row so it never contends with element or presence writes. Each bucket refills continuously at its rate up to a burst capacity; a call that can't spend a token is rejected rather than queued.

Validation bounds

Every inbound element, batch, and presence payload is validated server-side before it touches a row, so a hostile or buggy client can't bloat a room or smuggle oversized data past the working set.

The design assumes browsers crash, networks drop, and uploads fail halfway. Here is what happens when they do.

Revocation is reactive too. Disabling a share re-runs the collab queries every member is subscribed to, and the client flips to a revoked state immediately; bumping a room's epochforces every member to resync. And when Convex isn't configured, the storage routes return a clean 503 rather than crashing.

One codebase, two runtime modes. A single flag, NEXT_PUBLIC_LOCAL_DATA, decides whether the app talks to real services or stays entirely in the browser.

The switch is the exported shouldUseRemoteData flag: remote mode is on only when NEXT_PUBLIC_LOCAL_DATA is not 1 and the Convex URL is present. In local mode the library provider reads and writes localStorage, renders thumbnails as inline PNG data URLs, and the auth proxy short-circuits — so the Playwright suite runs the full UI with zero external services. Live collaboration depends on Convex and is therefore remote-only.

Running the full stack locally

Convex's _generatedfiles don't exist until the project is linked, so run the Convex dev server before building the backend.

# Link & run the Convex backend (creates _generated files)
pnpm exec convex dev

# In another terminal, run Next.js against your .env.local
pnpm dev

Wire up the three external services, then deploy. The steps below mirror README.md.

1. 1Copy .env.example to .env.local.
2. 2Link and push Convex with pnpm exec convex dev --once.
3. 3In .env.local, set CONVEX_DEPLOYMENT plus NEXT_PUBLIC_CONVEX_URL, CONVEX_SITE_URL, NEXT_PUBLIC_CONVEX_SITE_URL, and SITE_URL or BETTER_AUTH_URL.
4. 4In Convex env, set SITE_URL or BETTER_AUTH_URL, BETTER_AUTH_SECRET, and Google/GitHub OAuth credentials.
5. 5Create an R2 bucket and S3 API token, then fill the CLOUDFLARE_R2_* variables.
6. 6Configure R2 CORS to allow browser PUT uploads from your app origin.

OAuth callbacks

Better Auth handles all current sign-in and session state. GitHub and Google should redirect back to the Next.js app, where app/api/auth/[...all]/route.ts forwards the request to Convex.

GitHub local callback: http://localhost:3000/api/auth/callback/github
Google local callback: http://localhost:3000/api/auth/callback/google

GitHub production callback: https://your-domain.com/api/auth/callback/github
Google production callback: https://your-domain.com/api/auth/callback/google

Store SITE_URL or BETTER_AUTH_URL, BETTER_AUTH_SECRET, and the Google/GitHub client credentials in Convex env. Keeping them only in .env.local is not enough because Convex executes the Better Auth handler.

A conventional Next.js App Router layout, with Convex functions and shared library code split out.

app/            Next.js App Router — pages, layouts, route handlers
  api/          Presigned-URL brokers & share endpoints
  dashboard/    The library UI
  scenes/       The embedded Excalidraw editor
  share/        Public view (v) and edit (e) routes
components/     React components (editor, dashboard, collab, ui/)
convex/         Schema, queries, mutations, collab logic, crons
lib/            Storage access, R2 client, hashing, validation helpers
tests/          Playwright e2e + collab smoke suites

Route handlers under app/api broker presigned storage access and shared-scene operations. They never stream scene bytes themselves (except the cache-friendly thumbnail proxy).

Copy .env.example to .env.local and fill in the values for the services you use. Everything except NEXT_PUBLIC_LOCAL_DATA is required for production.

The project ships unit tests (Vitest + convex-test), end-to-end tests (Playwright, run in local demo mode), and a collaboration smoke suite.