Excalidraw · Architecture

Excalidraw: how the system is designed

Created · run_mwekgmm235095803148ecb19 · github.com/excalidraw/excalidraw @ master · commit 82d5847e57dc · model claude-opus-5-5

How the Excalidraw monorepo is built: an embeddable canvas editor published as seven npm packages, and the excalidraw.com web app that adds local saving, encrypted share links and live collaboration on top of it, against external services this repository does not contain.

7published npm packages
46module groups over 774 files
8data stores, all reached from the browser
33hosts called from code

1. What the system is

Excalidraw is an online whiteboard for drawing diagrams that look sketched by hand. Someone opens it in a web browser, draws boxes, arrows, text and pictures on an endless canvas, and can save the drawing, export it as an image, send a link to it, or draw on it together with other people at the same time. The drawing program itself runs entirely in the browser. When a drawing is shared or edited together, it is locked with a key before it leaves the computer, and the key travels only inside the link, so the servers that store and relay it cannot read it.

The repository holds two things built from one codebase. The first is the editor, published to npm as @excalidraw/excalidraw, a React component that any web product can embed. Seven npm packages live under packages/: @excalidraw/excalidraw, @excalidraw/common, @excalidraw/element, @excalidraw/math, @excalidraw/utils, @excalidraw/fractional-indexing and @excalidraw/laser-pointer. The second is excalidraw-app/, the excalidraw.com web app, which is not published. It is a thin shell around the editor that adds local saving, encrypted share links, live collaboration and the AI features.

Everything in the repository runs in the browser or in CI. The repository contains no server code. The collaboration server (excalidraw-room, production https://oss-collab.excalidraw.com), the share-link JSON backend (https://json.excalidraw.com/api/v2/), the AI backend (https://oss-ai.excalidraw.com) and the library backend (https://us-central1-excalidraw-room-persistence.cloudfunctions.net/libraries) are external services reached by URLs set in .env.production. Firebase (Firestore and Storage) holds collaboration rooms and shared images; its rules files are in firebase-project/, but nothing in the repository deploys them.

The actors

What the system is for: making a quick, informal diagram with no sign-up, keeping it private by default, and letting other products offer the same editor without building one.

Engineering standards

Engineering standards: 7/10, Good

Good. Standards are enforced mechanically: TypeScript strict, ESLint with --max-warnings=0, Prettier and tsc run on every pull request, vitest runs in CI, every action is SHA-pinned, and the boundaries are clear at package level with little duplication (8 groups, 118 lines). It is held back from 8 by size and coupling: App.tsx at 11,516 lines with an 852-line pointer-up handler, 76 files over 500 lines, 198 functions over 100 lines, 30 two-way module pairs, 14 empty error handlers, 0.30 test files per source file, and a pre-commit hook whose only command is commented out. The technical assessment gives the reasoning per criterion.

RatingScaleScore
Engineering standards7/10 Good
Security7/10 Good
Configuration and secrets6/10 Fair
Data and persistence7/10 Good
Error handling and resilience6/10 Fair
Availability and recovery5/10 Fair
Performance and scale8/10 Good
Each rating is reasoned in the section it names; 6 or below is carried into the risk register.

2. Business process

The process Excalidraw serves is short: a person has an idea, sketches it, keeps it, and gets it in front of someone else. There is no sign-up, no workspace and no document list on a server. Each step below is one a user would name, in the order they usually meet them. Four of them need a service outside the browser (sharing a link, collaborating, publishing a library and asking the AI); the rest never leave the browser tab.

who inside the browser tab external services Person drawing 1. Draw on the canvas shapes, arrows, text, images; undo and redo stays in the tab Automatic, no action 2. Save in the browser scene in localStorage, images in IndexedDB stays in the tab Person drawing 3. Export a file or image PNG, SVG, .excalidraw file, clipboard stays in the tab (a download) Person sharing, and anyone holding the link 4. Share a link encrypted first; key only in the #json= fragment JSON backend + Firebase Storage stores ciphertext and images, never the key Collaborators in a room 5. Collaborate live edits and cursors; key only in the #room= fragment Collaboration server + Firestore relays and keeps encrypted room scenes Person drawing; library authors 6. Install a library from an allowlisted URL; authors publish one Library site + library backend serves library files; receives submissions Person drawing 7. Generate a diagram from text Mermaid converts in the tab; AI prompts go out AI backend text-to-diagram and diagram-to-code, not E2E Developers; Excalidraw+ 8. Embed the editor npm package in a product, or the export iframe Host product owns storage, sharing and identity itself
Figure 2.1 · the business processWhich steps of using Excalidraw stay in the browser tab and which reach a service outside this repository. The dashed box is the tab; solid arrows cross to services that hold only what the browser sends them, encrypted except for the AI requests. The dashed arrow is a different boundary: the editor running inside someone else's product.
  1. Draw on the canvas. The person picks a tool and draws: rectangles, ellipses, diamonds, arrows that stay attached to shapes, free-hand lines, text and pasted images. Everything is undoable. Nothing is sent anywhere to do this.packages/excalidraw (the editor), packages/element (shapes)
  2. Save in the browser. There is no save button for the everyday case: the drawing is written to the browser's own storage a moment after each change, and images go to a separate browser database. Closing the tab and coming back restores it. Images not used for more than 24 hours, and not in the current drawing, are cleared out.excalidraw-app/data/LocalData.ts, excalidraw-app/data/localStorage.ts
  3. Export a file or image. The person downloads the drawing as a PNG or SVG picture, copies it to the clipboard, or saves an .excalidraw file that can be opened again later. This is the durable copy a person controls; it never touches a server.packages/excalidraw/data (export and JSON format)
  4. Share a link. The person asks for a link. The drawing is locked with a fresh key in the browser, the locked copy is uploaded, and the link that comes back carries the key after the #, the part a browser never sends to a server. Whoever opens the link gets their own copy of that snapshot.excalidraw-app/data/index.ts, excalidraw-app/share/ShareDialog.tsx
  5. Collaborate live. The person starts a session and sends the room link to others. Everyone in the room sees the same drawing and each other's cursors as they move; edits from all sides are merged. The room's drawing is also kept, still locked, so a latecomer or a reconnecting collaborator can catch up. A collaborator can set a display name.excalidraw-app/collab/Collab.tsx, excalidraw-app/collab/Portal.tsx, excalidraw-app/data/firebase.ts
  6. Install a library. The person browses the public library of ready-made shapes and installs one, which adds it to their side panel; only links from excalidraw.com and the official libraries repository are accepted. A library author goes the other way and publishes their own collection, with a name and optional handles, for review.packages/excalidraw/data/library.ts, packages/excalidraw/components/PublishLibrary.tsx
  7. Generate a diagram from text. The person writes Mermaid notation and gets an Excalidraw drawing back, converted in the browser; or describes a diagram in words and lets the AI draw it, or turns a sketched wireframe into code. The AI requests are the one place a drawing's content leaves the browser without being locked first.packages/excalidraw/components/TTDDialog, excalidraw-app/components/AI.tsx
  8. Embed the editor. A developer adds the editor to their own product from npm and decides where drawings are stored and who may see them; the editor brings no backend of its own. Excalidraw+ is a special case: it embeds a page of excalidraw.com and, after proving who it is, takes over the drawing that the person kept in their browser.packages/excalidraw (published as @excalidraw/excalidraw), excalidraw-app/ExcalidrawPlusIframeExport.tsx

What needs a server, then, is everything that involves a second person or a second device: share, collaborate, publish a library, and the AI. In each of those except the AI the server holds only encrypted data and never the key. Drawing, saving, exporting and Mermaid conversion need nothing but the browser, and installing a library only downloads a file, which is why excalidraw.com keeps working offline as an installed web app.

3. Entry points

The repository contains no server code, so there are no HTTP routes, queue consumers or schedulers of its own. Work enters in four places. The first is the browser: a page load, a URL fragment, a window or document event, a postMessage from another frame, or a Socket.IO event pushed by the external collaboration server. The second is the editor library, which an embedding application mounts as a React component and drives through its imperative API. The third is the developer's shell, through the yarn scripts in package.json. The fourth is GitHub Actions, through twelve workflows. The Docker image adds one more: the nginx server that serves the built app.

The evidence probe counted 172 addEventListener-style matches across 41 files and listed the first 120. Most of them are not entry points into the system. They are listeners that individual UI components attach while they are open (Popover, Dialog, EyeDropper, FileDropOverlay, the Minimap controller, ColorPicker, CursorHint, ElementLinkDialog, SearchMenu, LibraryMenu and others), the per-gesture pointer listeners the editor attaches during a drag, the eight overload and implementation lines of the addEventListener helper in packages/common/src/utils.ts:961-1027, a typed declaration in packages/common/src/promise-pool.ts, two test files, setupTests.ts, and the demo in examples/with-script-in-browser. The component-internal listeners share one row below, which names their files. The examples and tests are not part of the shipped system and get no row.

The inventory carries 59 rows. Two of them are easy to miss because neither is in the app's TypeScript: the legacy self-unregistering public/service-worker.js, and the inline analytics loader in excalidraw-app/index.html, which attaches a "load" listener when the app runs inside an iframe. Both run in the browser on page load, so both are counted with the web app shell.

KindRowsWhat enters here
Web app shell15Page load, the Excalidraw+ export path, the four URL fragments (#json=, #room=, #url=, #addLibrary), window lifecycle events, the install prompt, the colour-scheme query, the legacy service worker and the analytics loader.
Collaboration window events4Unload, online and offline status, and pointer and visibility activity while a room is open.
Socket.IO events7Messages pushed by the external collaboration server: room join, peers joining, peer list changes, encrypted scene and cursor broadcasts, first-in-room, follow changes, and connection failure.
Editor library11The Excalidraw component and its API, document and window listeners, canvas pointer input, clipboard, file drop, embed messages, OS file handling, the web share target, the diagram-to-code preview stream, the command palette shortcut, and one row for component-internal listeners.
CLI and build9yarn scripts a developer or CI job runs: dev server, builds, tests, release, performance stats, locale coverage and the install hook.
CI12GitHub Actions workflows triggered by pull requests and by pushes to "master", "release" and l10n_master.
Container1nginx serving the static build inside the Docker image.

Three URL fragments go through one function. On page load and on every hashchange, initializeScene (excalidraw-app/App.tsx:217) reads the fragment and decides what to load. #json=<id>,<key> fetches an encrypted scene from the share-link backend. #room=<roomId>,<roomKey> calls startCollaboration, which opens the Socket.IO connection. #url= fetches the scene file the link names. The fourth fragment, #addLibrary, is handled before them: useHandleLibrary registers its own hashchange listener, stops the event from propagating when the fragment carries a library URL, and checks that URL against ALLOWED_LIBRARY_URLS (excalidraw.com and raw.githubusercontent.com/excalidraw/excalidraw-libraries). The #url= path has no such allowlist. The /excalidraw-plus-export path skips the editor altogether: ExcalidrawApp renders ExcalidrawPlusIframeExport, which accepts postMessage only from VITE_APP_PLUS_APP and requires a JWT verified with RSASSA-PKCS1-v1_5 SHA-256 against VITE_APP_PLUS_EXPORT_PUBLIC_KEY before it posts the localStorage scene back to that origin.

Entry points 59 rows
KindTriggerWhereHandlerWhat it does
Web app shellPage load of excalidraw.comexcalidraw-app/index.tsx:16; excalidraw-app/App.tsx:1313ExcalidrawAppRoot component that index.tsx renders after loading the Sentry module and registering the PWA service worker. Routes the export path to the iframe exporter and otherwise mounts the editor inside an error boundary and the Jotai store.
Web app shell/excalidraw-plus-export pathexcalidraw-app/App.tsx:1315ExcalidrawPlusIframeExportRenders no editor; announces READY to the Excalidraw+ parent frame and waits for scene requests. Lets Excalidraw+ copy the user's locally stored scene into its own app.
Web app shell#json= share linkexcalidraw-app/App.tsx:217initializeSceneMatches the fragment, asks before replacing a non-empty local scene, then downloads and decrypts the scene from the JSON backend. Clears the fragment from the address bar once loaded.
Web app shell#room= collaboration linkexcalidraw-app/App.tsx:217 and 332initializeSceneRecognises a room link and calls startCollaboration with the room id and key, then reconciles whatever the room returns with the elements already on the canvas. Local storage is not overwritten for a room.
Web app shell#url= external sceneexcalidraw-app/App.tsx:231 and 303-320initializeSceneFetches whatever URL the fragment names and parses the response as a scene file. On failure it loads an error message instead of a scene; no host allowlist applies.
Web app shell#addLibrary fragment (or legacy query)packages/excalidraw/data/library.ts:677 and 922; called at excalidraw-app/App.tsx:446useHandleLibraryHook that loads the saved library and listens for library install links on load and on hash change. Validates the URL against the allowlist, fetches it and merges the items into the library, prompting unless the link carries the editor's own token.
Web app shellhashchangeexcalidraw-app/App.tsx:570 and 672onHashChangeWhen the new fragment is not a library link, leaves any collaboration room that the new URL is not for and runs initializeScene again. Replaces the canvas with the scene it returns.
Web app shellvisibilitychange, focus, blurexcalidraw-app/App.tsx:597, 660 and 674-676visibilityChangeOn blur or a hidden tab it flushes the pending local save; on focus or a visible tab it runs the debounced tab sync. That sync reloads the scene, library and images when another tab wrote newer data to browser storage.
Web app shellbeforeunloadexcalidraw-app/App.tsx:691 and 709unloadHandlerFlushes the pending local save and asks the browser to confirm leaving while image files are still being saved. The prompt is skipped when VITE_APP_DISABLE_PREVENT_UNLOAD is "true".
Web app shellunloadexcalidraw-app/App.tsx:656 and 673onUnloadFlushes the debounced save to localStorage and IndexedDB so the last edit is not lost when the tab closes.
Web app shellbeforeinstallpromptexcalidraw-app/App.tsx:180module-level arrow functionSuppresses the browser's automatic PWA install prompt and keeps the event so the app's own install button can show it later.
Web app shellmessage from the Excalidraw+ parentexcalidraw-app/ExcalidrawPlusIframeExport.tsx:157 and 205handleMessageRejects any origin other than VITE_APP_PLUS_APP, verifies the JWT in a scene request, then reads the scene from localStorage and posts it back to that origin. Posts an ERROR message instead when verification or parsing fails.
Web app shellColour-scheme media query changeexcalidraw-app/useHandleAppTheme.ts:25 and 30handleChangeWhen the app theme is set to "system", switches the editor between light and dark as the operating system's preference changes.
Web app shellService worker install and activatepublic/service-worker.js:7 and 11anonymous worker listenersA self-destroying worker kept for browsers that still run the old Create React App service worker. It activates at once, unregisters itself and reloads every open client so the Vite PWA worker can take over.
Web app shellAnalytics script "load" (production build, inside an iframe)excalidraw-app/index.html:219-248inline scriptInjects the Simple Analytics script; when the page is embedded in an iframe, a "load" listener sends an "iframe" "embed" event with the path. The listener passes an action variable that the script never declares.
Collaboration windowbeforeunloadexcalidraw-app/collab/Collab.tsx:219 and 310beforeUnloadWhile collaborating, if files are still uploading or the scene is not yet in Firestore, starts a Firestore save and asks the browser to confirm leaving. The prompt is skipped when VITE_APP_DISABLE_PREVENT_UNLOAD is "true".
Collaboration windowonline and offlineexcalidraw-app/collab/Collab.tsx:220-221 and 273onOfflineStatusChangeDebounced handler that records whether the browser is offline in a Jotai atom, which the UI uses to show an offline warning.
Collaboration windowunloadexcalidraw-app/collab/Collab.tsx:222 and 306onUnloadCloses the Socket.IO client and tears down the collaboration session as the tab closes.
Collaboration windowpointermove and visibilitychange while in a roomexcalidraw-app/collab/Collab.tsx:832, 848 and 882-883onPointerMove, onVisibilityChangeDrive the collaborator idle state: pointer movement restarts the 60,000 ms idle timer and the 3,000 ms active heartbeat. A hidden tab reports "away" and a visible one reports "active" to the room.
Socket.IOinit-roomexcalidraw-app/collab/Portal.tsx:43arrow function registered when the portal opens the socketReplies with join-room and the room id, then records a "room joined" analytics event.
Socket.IOnew-userexcalidraw-app/collab/Portal.tsx:49arrow function registered when the portal opens the socketBroadcasts the full scene, encrypted, as an INIT message so the newcomer receives the current drawing from a peer.
Socket.IOroom-user-changeexcalidraw-app/collab/Portal.tsx:56setCollaboratorsReplaces the collaborator list with the socket ids the server reports as present in the room.
Socket.IOclient-broadcastexcalidraw-app/collab/Collab.tsx:589arrow function in startCollaborationDecrypts each peer message with the room key and dispatches it by subtype: scene INIT and UPDATE are reconciled into the canvas, and MOUSE_LOCATION, USER_VISIBLE_SCENE_BOUNDS and IDLE_STATUS update the peer's cursor, viewport and status. The first INIT also completes room initialisation.
Socket.IOfirst-in-roomexcalidraw-app/collab/Collab.tsx:698initializeRoomRuns once when the server says nobody else is in the room: loads the stored scene from Firestore and resolves the scene that startCollaboration returns.
Socket.IOuser-follow-room-changeexcalidraw-app/collab/Collab.tsx:709arrow function in startCollaborationRecords which peers are following this user and immediately rebroadcasts this user's visible scene bounds so their viewports catch up.
Socket.IOconnect_errorexcalidraw-app/collab/Collab.tsx:552fallbackInitializationHandlerWhen the socket cannot connect, loads the room's scene from Firestore instead. The same handler fires if no initial scene arrives within 5,000 ms.
Editor libraryMounting the component and calling its APIpackages/excalidraw/index.tsx:68 and 418ExcalidrawThe published React component (a memo of the base component) that an embedding app renders. It hands back the imperative API (updateScene, getAppState, updateLibrary and the rest) through a callback or the API provider component.
Editor libraryKeyboard, wheel, gesture, resize, scroll, fullscreen and focus eventspackages/excalidraw/components/App.tsx:4011addEventListenersRemoves and re-attaches every document and window listener the editor needs, including keydown and keyup, wheel and Safari gesture events, paste, cut, copy, resize, unload, blur, fullscreen change and (when enabled) scroll. Each registration returns an unsubscribe callback collected for teardown.
Editor libraryPointer down on the interactive canvaspackages/excalidraw/components/App.tsx:7547handleCanvasPointerDownThe start of every drawing, selecting, dragging and panning gesture. It routes view-only editors to panning and otherwise sets up the pointer-down state and the window listeners that follow the drag.
Editor libraryClipboard copy, cut, "paste"packages/excalidraw/components/App.tsx:4193, 4243 and 4249; App.clipboard.ts:84, 99 and 320onCopy, onCut, pasteFromClipboardCopy and cut write the selected elements to the system clipboard (cut then deletes them). Paste reads elements, images, text, SVG or Mermaid from the clipboard and inserts them into the scene.
Editor libraryDrag and drop of filespackages/excalidraw/components/App.tsx:2440 and 10789handleAppOnDropParses the dropped data transfer and loads a scene or library file, or inserts images and text at the drop point. The native drop is cancelled at the container even when dropping is disabled, so the browser does not navigate to the file.
Editor librarymessage from YouTube and Vimeo embedspackages/excalidraw/components/App.tsx:1117 and 4020onWindowMessageIgnores every origin except https://player.vimeo.com and https://www.youtube.com. Tracks YouTube player states and answers Vimeo pause messages so embedded videos play and pause correctly.
Editor libraryOperating-system file open (File Handling API launchQueue)packages/excalidraw/components/App.tsx:3589loadFileToCanvas (via the launch consumer)When the installed PWA is opened with a .excalidraw file, the consumer reads the first file handle and loads it onto the canvas, keeping the handle for later saves.
Editor libraryWeb share target (?web-share-target)packages/excalidraw/components/App.tsx:3899 and 4920restoreFileFromShareReads the file stored under "shared-file" in the "web-share-target" cache, loads it onto the canvas and deletes it. The manifest declares POST /web-share-target, but nothing in the repository writes that cache entry.
Editor librarymessage carrying a diagram-to-code partialpackages/excalidraw/components/App.tsx:1903, 1918 and 1924onPartialMessageScript injected into the generated preview iframe: it writes each longer HTML snapshot of type excalidraw:diagramToCode:partial into the document so the preview renders while the AI response streams. It re-registers itself after document.open() wipes the listeners.
Editor libraryCommand palette shortcut (keydown, capture)packages/excalidraw/components/CommandPalette/CommandPalette.tsx:160 and 180commandPaletteShortcutToggles the command palette dialog on its keyboard shortcut and records a command_palette analytics event when it opens.
Editor libraryComponent-internal UI listenerscomponents/App.pan.ts, App.toolDrag.ts, App.tsx:7963-7966, 8284-8285 and 10706-10711, ColorPicker/ColorPicker.tsx, ColorPicker/Picker.tsx, CommandPalette.tsx:808, CursorHint.tsx, Dialog.tsx, ElementLinkDialog.tsx, EyeDropper.tsx, FileDropOverlay.tsx, LibraryMenu.tsx, Minimap/minimap-controller.chunk.ts, Popover.tsx, SearchMenu.tsx, Sidebar/Sidebar.tsx, Stats/DragInput.tsx, TTDDialog/*.tsx, TopPicksDnD/topPicksDnD.tsx, dropdownMenu/DropdownMenuContent.tsx, hyperlink/Hyperlink.tsx, hooks/useCreatePortalContainer.ts, hooks/useOutsideClick.ts, hooks/useScrollPosition.ts, renderer/animation.ts, wysiwyg/textWysiwyg.tsx, index.tsx:200 (all under packages/excalidraw)per-component handlersListeners a component attaches while it is open or a gesture is in progress (closing on outside click or Escape, following a drag, sampling colour, live drop highlighting, minimap panning). They react to input inside the editor rather than bringing new work into it.
CLI and buildyarn startpackage.json; excalidraw-app/package.jsonvite dev serverInstalls dependencies and starts the Vite development server for excalidraw-app with the values from .env.development.
CLI and buildyarn build, build:app:dockerpackage.json; excalidraw-app/package.json:45-48vite build, scripts/build-version.jsbuild runs build:app (which sets VITE_APP_ENABLE_TRACKING=true and the Vercel commit SHA) and then writes the version file. build:app:docker builds the same app with VITE_APP_DISABLE_SENTRY=true for the image.
CLI and buildyarn build:packagesscripts/buildBase.js, scripts/buildPackage.js, scripts/buildUtils.jsesbuild scriptsBuilds common, fractional-indexing, laser-pointer, math, element and excalidraw in dependency order with esbuild and generates their type declarations. buildPackage.js inlines the values parsed from the root .env files.
CLI and buildyarn test:allpackage.jsontsc, eslint, prettier, vitestRuns the type check, ESLint with zero warnings allowed, the Prettier check and the Vitest suite once, in that order.
CLI and buildyarn release (--tag=test|next|latest)scripts/release.jsrelease.jsBuilds and publishes the common, fractional-indexing, math, element and excalidraw packages to npm under the given tag, with a hash-suffixed version for test and next. For latest it also takes a version and updates the changelog.
CLI and buildyarn stats:perf, stats:comparescripts/stats/perf.mjsperf.mjsMeasures page load and pan and zoom of a large scene in Playwright Chromium on a throttled connection. In compare mode it builds and measures two builds side by side and prints their differences.
CLI and buildnode scripts/stats/post.mjsscripts/stats/post.mjspost.mjsPosts a perf.json comparison or a bundle-stats.json file to the Excalidraw+ stats API, authenticated with OSS_STATS_TOKEN.
CLI and buildyarn locales-coveragescripts/build-locales-coverage.jsbuild-locales-coverage.jsCounts the translated keys in each locale file under packages/excalidraw/locales and writes the percentages to percentages.json.
CLI and build"prepare" install hookpackage.json (scripts.prepare); .husky/pre-commithusky installRuns on every yarn install and installs the git hooks. The pre-commit hook's only command, yarn lint-staged, is commented out, so the installed hook runs nothing.
CIpull_request.github/workflows/lint.ymllint jobRuns the Prettier check, ESLint with --max-warnings=0 and tsc on every pull request.
CIpush to master.github/workflows/test.ymltest jobInstalls dependencies and runs the Vitest suite.
CIpull_request.github/workflows/test-coverage-pr.ymlcoverage jobRuns Vitest with coverage and posts the coverage report on the pull request.
CIpull_request to master.github/workflows/size-limit.ymlsize jobChecks the bundle size against its limits with size-limit-action and reports the result on the pull request.
CIpush to master, workflow_dispatch.github/workflows/stats.ymlbundle and perf jobsBuilds bundle stats and runs the performance comparison against the previous commit, then posts both with post.mjs to backend.excalidraw.com.
CIpull_request (opened, edited, synchronize, labeled, unlabeled).github/workflows/semantic-pr-title.ymlsemantic jobChecks that the pull request title follows the conventional commit format.
CIpush to release, pull_request.github/workflows/cancel.ymlcancel jobCancels earlier runs of the same workflow on the branch so only the newest push is built.
CIpush to release.github/workflows/autorelease-excalidraw.ymlAuto-release-excalidraw-next jobSets the npm token from NPM_TOKEN and runs release.js with --tag=next --non-interactive, publishing the @excalidraw packages to npm with tag next.
CIpush to release.github/workflows/build-docker.ymlbuild-docker jobRuns docker build on the repository to confirm the image builds; it does not push.
CIpush to release.github/workflows/publish-docker.ymlpublish-docker jobLogs in to Docker Hub and builds and pushes excalidraw/excalidraw:latest for linux/amd64, linux/arm64 and linux/arm/v7.
CIpush to release.github/workflows/sentry-production.ymlsentry jobBuilds the app, installs sentry-cli by piping https://sentry.io/get-cli/ to bash, and creates a Sentry production release with commits and sourcemaps. The sourcemap path, ./build/static/js/, is not where the Vite build writes its output.
CIpush to l10n_master.github/workflows/locales-coverage.ymllocales jobRuns locales-coverage, commits a changed percentages.json back to the branch with PUSH_TRANSLATIONS_COVERAGE_PAT, and writes the coverage summary into the pull request description.
ContainerHTTP request to the container (port 80)Dockerfilenginx:stable-alpine-slimServes the static excalidraw-app/build output with nginx's default configuration. The image declares a HEALTHCHECK that fetches http://localhost with wget.

Functions the handlers call

The handlers above hand most of their work to a small set of functions. These are the ones named in this section.

Functions the handlers call 18 rows
FunctionWhereWhat it does
startCollaborationexcalidraw-app/collab/Collab.tsx:492Joins the room in a #room= link, or creates a new room with a random id and key when the share dialog starts a session (ShareDialog.tsx:204). It pauses local saving, opens the Socket.IO connection to VITE_APP_WS_SERVER_URL and registers the room's socket handlers.
initializeRoomexcalidraw-app/collab/Collab.tsx:725Cancels the fallback timer and connect_error listener, and when asked to fetch the scene, loads and decrypts the room's scene from Firestore. Marks the socket as initialised either way.
handleRemoteSceneUpdateexcalidraw-app/collab/Collab.tsx:821Writes reconciled remote elements into the scene without adding an undo entry, then loads any image files the new elements reference.
decryptPayloadexcalidraw-app/collab/Collab.tsx:469Decrypts a socket message with the room key and parses it as JSON. On failure it alerts the user and returns an INVALID_RESPONSE message.
initializeIdleDetectorexcalidraw-app/collab/Collab.tsx:881Attaches the document pointermove and visibilitychange listeners that drive the collaborator idle state.
broadcastSceneexcalidraw-app/collab/Portal.tsx:142Encrypts and sends the scene to the room as an INIT or UPDATE message, sending only elements whose version changed since the last broadcast unless a full sync is requested.
getCollaborationLinkDataexcalidraw-app/data/index.ts:138Parses the room id and key out of a #room= fragment. Alerts and returns nothing when the key is not 22 characters long.
generateCollaborationLinkDataexcalidraw-app/data/index.ts:148Generates a new random room id and a new encryption key for a collaboration session.
importFromBackendexcalidraw-app/data/index.ts:202Downloads a share-link scene from the JSON backend by id, decompresses and decrypts it with the key from the fragment, and falls back to the legacy format if that fails. Alerts and returns an empty scene when the request or decoding fails.
syncDataexcalidraw-app/App.tsx:597Debounced tab sync: when another tab has written newer data to browser storage and this tab is not collaborating, reloads the scene, username, language, library and missing image files from storage.
flushSaveexcalidraw-app/data/LocalData.ts:156Runs the pending debounced save immediately, writing the scene to localStorage and new image files to IndexedDB.
verifyJWTexcalidraw-app/ExcalidrawPlusIframeExport.tsx:89Verifies a JWT's RSASSA-PKCS1-v1_5 SHA-256 signature against the configured public key with Web Crypto and rejects it if exp is present and past. Throws on any failure.
parseLibraryTokensFromUrlpackages/excalidraw/data/library.ts:530Reads the library URL from the #addLibrary fragment (or the legacy query parameter) and the optional token beside it.
validateLibraryUrlpackages/excalidraw/data/library.ts:497Accepts a library URL only if its host and path fall under an entry of ALLOWED_LIBRARY_URLS or pass a validator the host app supplies. Throws otherwise.
importLibraryFromURLpackages/excalidraw/data/library.ts:718Validates and fetches a library file, waits for the tab to be focused if it must prompt, and merges the items into the library as published. Removes the install parameter from the URL afterwards.
loadFileToCanvaspackages/excalidraw/components/App.tsx:10937Loads a dropped, opened or shared file into the editor, as a scene or a library depending on its contents, and keeps the file handle for saving back.
addEventListenerpackages/common/src/utils.ts:961-1027Typed wrapper that attaches a listener to a window, document, element or font set, tolerating a missing target. Returns a function that removes the listener.
registerSWexcalidraw-app/index.tsx:15Registers the Workbox service worker that vite-plugin-pwa generates, which precaches the app and caches fonts and locale files for offline use.

4. Module boundaries

A filesystem has no modules, so this section groups files by path prefix and counts the calls and imports that cross from one group to another. The grouping and both tables come from modules.cjs, run with its defaults (--big 25, --min-child 8) over the whole repository rather than a src/ folder, because this monorepo has none at its root. The grouping rule, verbatim:

grouping rule

grouped by path prefix under ./, starting at depth 2; a group over 25 files is split one level deeper, and only children with 8+ files are promoted.

That rule yields 46 module groups over 774 files. Two consequences matter when reading the tables. First, a large folder keeps only its own files and the subfolders too small to promote: packages/excalidraw (49 files) is the package's top-level files plus small subfolders such as scene/, wysiwyg/, eraser/ and lasso/, while components, actions, data, renderer and the rest stand as groups of their own. Second, three groups are not directories at all: (repo root), @docusaurus and @excalidraw also hold the graph nodes for third-party packages imported by bare name (vite, esbuild, pica, the Docusaurus presets, @excalidraw/random-username and @excalidraw/mermaid-to-excalidraw), which the graph files under the scope they were imported from.

The seven npm packages map onto these groups as follows: @excalidraw/excalidraw is packages/excalidraw and its eighteen subgroups, @excalidraw/element is packages/element/src, @excalidraw/common is packages/common/src, @excalidraw/math is packages/math/src, and @excalidraw/utils, @excalidraw/fractional-indexing and @excalidraw/laser-pointer are each one small group. excalidraw-app and its six subgroups are the excalidraw.com web app, which is not published.

Module groups

One row per group, largest first, with the file count modules.cjs printed and one line on what the group owns. To find which group a particular function, class or type sits in, and what calls it, look the name up in the symbol index.

Module groups 46 rows
FilesModuleWhat it owns
147packages/excalidraw/componentsThe editor's React UI: App.tsx (the class component that holds editor state and handles every pointer, keyboard and paste event), the canvases, layer UI, dialogs, toolbars, library menu and every component folder under 8 files.
82packages/excalidraw/testsVitest suites, fixtures and test helpers for the editor package.
58packages/element/srcThe element model published as @excalidraw/element: creating, mutating, binding, resizing, hit-testing, measuring and drawing elements, plus the Scene.ts and store.ts state containers.
50packages/excalidraw/actionsThe action registry: each user command (undo, align, group, export, style changes) as an action object with its own update logic and UI, dispatched by the action manager.
49packages/excalidrawThe package's top-level files and small subfolders: the entry point index.tsx, public types, history, clipboard, i18n, snapping, scene export (scene/), text editing (wysiwyg/), eraser and lasso.
41packages/excalidraw/components/TTDDialogThe text-to-diagram dialog: Mermaid editor and preview, the AI chat panel and its streaming fetch, and chat history storage.
28packages/element/testsTests for the element package.
21packages/common/srcShared constants, colours, keys, utilities, the event emitter, queues and the app event bus, published as @excalidraw/common.
17packages/excalidraw/components/dropdownMenuThe dropdown menu component family (items, groups, submenus, triggers).
16packages/math/src2D geometry published as @excalidraw/math: points, vectors, lines, segments, curves, ellipses, polygons, angles and ranges.
15packages/excalidraw/dataScene data handling: JSON serialisation, restore, reconcile, compression, encryption, library storage, blob and file system access.
14excalidraw-appThe excalidraw.com shell: App.tsx, app constants, Sentry setup, the Excalidraw+ iframe export, the Vite config and the app entry point.
14packages/excalidraw/components/StatsThe stats panel that edits position, size, angle and font size of the selection.
13packages/excalidraw/fontsThe font registry and font-face loading for the bundled families (Excalifont, Virgil, Nunito, Cascadia, Xiaolai and others).
13(repo root)Root configuration (package.json, tsconfig.json, vitest.config.mts, vercel.json, .eslintrc.json, .lintstagedrc.js, setupTests.ts) and graph nodes for bare-name imports such as vite, esbuild, next and pica.
12packages/excalidraw/components/ColorPickerThe colour picker: palettes, shades, custom colours, top picks and keyboard navigation.
12packages/excalidraw/hooksReact hooks shared by the editor components.
11excalidraw-app/dataApp persistence: localStorage and IndexedDB saving, the Firebase client, share-link export and import against the JSON backend, the file manager and tab sync.
11examples/with-script-in-browserExample of embedding the editor in a Vite browser app.
11scriptsBuild and release scripts: esbuild package builds, WASM build, locales coverage, changelog and release.
10excalidraw-app/componentsApp-only UI: main menu, sidebar, welcome screen, footer, AI integration, Excalidraw+ export and promo, top-level error boundary.
10packages/excalidraw/components/SidebarThe sidebar component, its header and tabs.
9packages/utils@excalidraw/utils: export and shape helpers for use outside the editor, with its tests and package config.
9packages/excalidraw/subsetFont subsetting with HarfBuzz and WOFF2 WebAssembly, run in a worker for export.
9packages/excalidraw/rendererThe static, interactive, new-element and SVG scene renderers, snapping guides and animation.
9packages/commonPackage configuration of @excalidraw/common and its tests, outside src/.
9packages/math/testsTests for the math package.
8packages/excalidraw/chartsCharts generated from pasted spreadsheet data (bar, line and radar).
8examples/with-nextjsExample of embedding the editor in a Next.js app, app router and pages router.
7dev-docs/srcPages and components of the Docusaurus developer documentation site.
7packages/laser-pointer@excalidraw/laser-pointer: the laser trail state and path simplification.
6dev-docsDocusaurus configuration for the developer documentation site.
4scripts/statsBundle size and performance benchmark scripts that stats.yml posts.
4excalidraw-app/testsTests for the app: collaboration, Firebase, language list, mobile menu.
4packages/fractional-indexing@excalidraw/fractional-indexing: order keys that keep element z-order stable across peers.
4packages/elementPackage configuration of @excalidraw/element, outside src/.
3excalidraw-app/collabLive collaboration: Collab.tsx (the session) and Portal.tsx (its Socket.IO connection), plus the error indicator.
3excalidraw-app/shareThe share dialog and its QR code.
3excalidraw-app/app-languageLanguage detection, language state and the language picker.
3packages/mathPackage configuration of @excalidraw/math.
3@docusaurusNot a directory: graph nodes for the Docusaurus packages the docs site imports.
2scripts/woff2esbuild and Vite plugins that handle WOFF2 font files.
2@excalidrawNot a directory: graph nodes for @excalidraw/random-username and @excalidraw/mermaid-to-excalidraw, npm packages published from other repositories.
1packagestsconfig.base.json, the TypeScript base shared by the packages.
1.huskyThe pre-commit hook.
1publicservice-worker.js, a self-unregistering worker that removes service workers left by the old Create React App build.

Cross-module edges

modules.cjs prints the 20 heaviest cross-module edges, counting calls and imports with both ends in the repository. A further 183 smaller edges were not printed, so this table is the top of the distribution, not all of it. No edges were ignored for having an end outside the scan root.

Cross-module edges, top 20 20 rows
CountFromTo
1015packages/excalidraw/componentspackages/element/src
669packages/excalidraw/componentspackages/excalidraw
653packages/element/srcpackages/math/src
622packages/excalidraw/actionspackages/element/src
521packages/excalidraw/componentspackages/common/src
467packages/element/srcpackages/common/src
296packages/excalidrawpackages/element/src
233packages/excalidraw/testspackages/element/src
209packages/excalidraw/components/Statspackages/element/src
200packages/excalidraw/actionspackages/excalidraw
192packages/excalidraw/rendererpackages/element/src
182packages/element/testspackages/element/src
182packages/excalidraw/testspackages/common/src
181packages/excalidraw/componentspackages/excalidraw/actions
179packages/excalidraw/actionspackages/common/src
167packages/excalidrawpackages/common/src
166packages/excalidraw/actionspackages/excalidraw/components
157packages/excalidraw/testspackages/excalidraw
136packages/excalidraw/datapackages/element/src
105packages/excalidraw/datapackages/common/src

The figure below is generated from the same output. It draws 45 modules, not 46: it omits the (repo root) group, which takes part in none of the 20 edges drawn. 11 modules take part in drawn edges and the other 34 sit under “no edge drawn”. The excalidraw-app groups are all in that lower block, because every edge into or out of the app is smaller than the 105 that closes the top 20.

module dependencies 105 136 157 166 167 179 181 182 182 192 200 209 233 296 467 521 622 653 669 1015 no edge drawn .husky 1 file @docusaurus 3 files @excalidraw 2 files dev-docs 6 files dev-docs/src 7 files examples/with-nextjs 8 files examples/with-script-in-browser 11 files excalidraw-app 14 files excalidraw-app/app-language 3 files excalidraw-app/collab 3 files excalidraw-app/components 10 files excalidraw-app/data 11 files excalidraw-app/share 3 files excalidraw-app/tests 4 files packages 1 file packages/common 9 files packages/common/src 21 files packages/element 4 files packages/element/src 58 files packages/element/tests 28 files packages/excalidraw 49 files packages/excalidraw/actions 50 files packages/excalidraw/charts 8 files packages/excalidraw/components 147 files packages/excalidraw/components/ColorPicker 12 files packages/excalidraw/components/Sidebar 10 files packages/excalidraw/components/Stats 14 files packages/excalidraw/components/TTDDialog 41 files packages/excalidraw/components/dropdownMenu 17 files packages/excalidraw/data 15 files packages/excalidraw/fonts 13 files packages/excalidraw/hooks 12 files packages/excalidraw/renderer 9 files packages/excalidraw/subset 9 files packages/excalidraw/tests 82 files packages/fractional-indexing 4 files packages/laser-pointer 7 files packages/math 3 files packages/math/src 16 files packages/math/tests 9 files packages/utils 9 files public 1 file scripts 11 files scripts/stats 4 files scripts/woff2 2 files
Figure 1 · module dependenciesGenerated from modules.cjs, so it matches the tables in this section exactly. Columns are dependency depth: a module sits one column right of everything that calls into it. Line thickness is the number of calls and imports crossing that boundary, and an edge that loops underneath is a cycle, drawn rather than hidden. The 34 modules under “no edge drawn” take part in none of the edges shown, heaviest first. The accented box is the module with the most files.

Intended layering, and where it does not hold

The packages are meant to stack in one direction: common, then math, then element, then excalidraw, then excalidraw-app, each depending only on the ones before it. The figure shows that this holds for the heavy traffic. packages/element/src sends 653 edges to packages/math/src and 467 to packages/common/src, and the editor's packages/excalidraw/components and packages/excalidraw/actions sit to the left of everything they call. The app, excalidraw-app, consumes the editor package and no package code calls back into it: the one edge from packages/excalidraw to excalidraw-app (the pair at 30 / 1) links packages/excalidraw/package.json to excalidraw-app/package.json, and the only other reference is the editor's test utilities reading excalidraw-app/app_constants.ts.

That order is the one the package manifests declare: packages/math/package.json declares @excalidraw/common as a dependency, packages/common/package.json declares no dependency on math, and element declares both. The code edges between common and math run mostly the other way, 15 from packages/common/src into packages/math/src (colors.ts, points.ts and utils.ts import from @excalidraw/math) against 4 back (range.ts imports a branding helper from common), so the pair is a cycle whichever order is taken as intended.

Two-way pairs

modules.cjs prints 30 two-way pairs: pairs of groups with edges in both directions, which a layered picture cannot show. The ones that cut across the intended layering are these six:

The remaining 24 pairs are mostly a parent folder and a promoted child (the dropdownMenu, Sidebar, Stats and ColorPicker folders with the components folder; the collab and data folders with the excalidraw-app root) or a tests folder paired with code that keeps test files beside it (wysiwyg/textWysiwyg.test.tsx and clipboard.test.ts in the package root import helpers from packages/excalidraw/tests). All 30 are listed with both counts.

Two-way pairs 30 rows
Module AModule BA to BB to A
packages/excalidraw/componentspackages/element/src10153
packages/excalidraw/componentspackages/excalidraw66917
packages/element/srcpackages/common/src4676
packages/excalidrawpackages/element/src29676
packages/excalidraw/actionspackages/excalidraw20010
packages/excalidraw/componentspackages/excalidraw/actions181166
packages/excalidrawpackages/common/src16711
packages/excalidraw/testspackages/excalidraw15715
packages/excalidraw/componentspackages/excalidraw/data762
packages/excalidraw/datapackages/excalidraw6629
packages/excalidraw/componentspackages/excalidraw/hooks447
packages/excalidraw/components/TTDDialogpackages/excalidraw/components441
packages/excalidraw/testspackages/excalidraw/actions4116
excalidraw-appexcalidraw-app/data3811
excalidraw-app/collabexcalidraw-app/data371
packages/excalidraw/testspackages/excalidraw/components376
packages/excalidraw/rendererpackages/excalidraw3514
excalidraw-apppackages/excalidraw301
packages/excalidraw/components/ColorPickerpackages/excalidraw/components271
packages/excalidraw/componentspackages/excalidraw/renderer246
packages/excalidraw/components/dropdownMenupackages/excalidraw/components2016
packages/excalidraw/components/Statspackages/excalidraw/components192
packages/element/srcpackages/utils1817
packages/excalidraw/components/Sidebarpackages/excalidraw/components187
excalidraw-appexcalidraw-app/components165
packages/common/srcpackages/math/src154
excalidraw-app/collabexcalidraw-app128
packages/excalidrawpackages/utils102
packages/excalidraw/hookspackages/excalidraw82
packages/excalidraw(repo root)21

5. Layered call graph

The module figure in section 4 shows which folders depend on which; this section shows the backbone of calls inside them. It is two figures because the repository has two backbones that the call graph does not join. Figure 5.1 is the excalidraw.com app: how a scene is loaded, saved in the browser, exported as a share link and synchronised in a collaboration room, down to the encryption calls in the editor package. Figure 5.2 is the editor core: how a pointer press becomes an element and how elements reach the screen and an exported image.

Both are drawn from graphdata.json, not from reading the code. Every one of the 41 edges drawn was checked present in the graph, matching on the function name with the call parentheses and the leading dot the graph gives class methods stripped. They are not complete call graphs: each draws only the calls that carry a scene between layers, and leaves out helpers, error paths and the hundreds of calls inside packages/excalidraw/components/App.tsx. Layers run from left to right in figure 5.1 and from top to bottom in figure 5.2, so each function sits after everything drawn that calls it. Accented boxes are the shared library underneath: packages/excalidraw/data in figure 5.1 and packages/element in figure 5.2.

entry app shell and collaboration app data firestore document encryption wrapper packages/excalidraw/data local and share link live collaboration importFromLocalStorage importFromBackend decompressData initializeScene ExcalidrawWrapper save serializeAsJSON exportToBackend compressData saveFilesToFirebase restoreElements reconcileElements _reconcileElements startCollaboration initializeRoom saveCollabRoomToFirebase decryptPayload loadFromFirebase saveToFirebase decryptElements createFirebaseSceneDocument encryptElements decryptData encryptData syncElements broadcastElements broadcastScene _broadcastSocketData
Figure 5.1 · layered call graph A: app shell, collaboration and persistence28 functions and 31 calls, each present in graphdata.json. Above the dashed line, the excalidraw.com shell loads a scene (from localStorage or a #json= share link), saves it locally and exports share links. Below it, the collaboration class in Collab.tsx and its socket wrapper in Portal.tsx sync a room through Firestore and Socket.IO. Everything leaving the browser passes through encryptData first. Three hops are not drawn because the graph has no edge for them, each being a call through an object reference: from ExcalidrawWrapper to the collaboration class (the shell holds it as a collab API object, and initializeScene calls startCollaboration on that object for a #room= link), from ExcalidrawWrapper's change handler to syncElements, and from broadcastElements to broadcastScene (the call goes through the collaboration class's portal property). That is why startCollaboration, syncElements and broadcastScene stand as separate entries.
pointer input static canvas export interactive canvas App handleCanvasPointerDown createGenericElementOnPointerDown newElement StaticCanvas exportToCanvas renderStaticScene renderElement drawElement drawElementOnCanvas generateElementShape InteractiveCanvas renderInteractiveScene
Figure 5.2 · layered call graph B: editor core13 functions and 10 calls, each present in graphdata.json. Input and output are separate paths that meet only in the scene the App component holds. A pointer press on the canvas runs handleCanvasPointerDown, which for a shape tool calls createGenericElementOnPointerDown and newElement. The screen and an exported image share one renderer: StaticCanvas and exportToCanvas both call renderStaticScene, which walks the elements and draws each one through renderElement, drawElement and drawElementOnCanvas down to the cached rough.js shape from generateElementShape. The interactive canvas (selection, handles, remote cursors) is a second canvas on top with its own renderer. The App component reaches the two canvas components by rendering them, so there is no call edge from it to either.

Functions drawn

One row per function in the two figures, 28 from figure 5.1 and 13 from figure 5.2, with the file and line of its definition.

Functions in the layered call graph 41 rows
FunctionWhereFigureWhat it does
ExcalidrawWrapperexcalidraw-app/App.tsx:3755.1The excalidraw.com root component: mounts the editor, loads the opening scene, saves each change locally or hands it to the collaboration session, and runs share-link export.
initializeSceneexcalidraw-app/App.tsx:2175.1Decides where the opening scene comes from (localStorage, a #json= share link, a #url= link or a #room= collaboration link) and returns it restored. For a room link it starts collaboration through the collab API object.
importFromBackendexcalidraw-app/data/index.ts:2025.1Fetches an encrypted share-link scene from the JSON backend by id and decrypts and decompresses it with the key from the URL fragment, falling back to the legacy format.
importFromLocalStorageexcalidraw-app/data/localStorage.ts:375.1Reads the saved elements and app state from localStorage and parses them, returning empty data when storage is unavailable or the JSON is unreadable.
exportToBackendexcalidraw-app/data/index.ts:2485.1Creates a share link: generates a key, serialises, compresses and encrypts the scene, posts it to the JSON backend and uploads its images to Firebase Storage. Returns the URL with the id and key in the fragment, or an error message.
saveexcalidraw-app/data/LocalData.ts:1445.1The LocalData class's save: queues a debounced write (300 ms) of elements and app state to localStorage and of image files to IndexedDB. Does nothing while saving is paused, as it is during collaboration.
startCollaborationexcalidraw-app/collab/Collab.tsx:4925.1Opens or joins a room: creates a room id and key when none is given, pauses local saving, connects Socket.IO and installs the handlers that decrypt and merge incoming scenes.
initializeRoomexcalidraw-app/collab/Collab.tsx:7255.1Finishes room setup when the first scene arrives or the socket fails: when asked to, loads the stored scene from Firestore, and marks the socket initialised either way.
saveCollabRoomToFirebaseexcalidraw-app/collab/Collab.tsx:3345.1Saves the room's syncable elements to Firestore and merges back what was stored. On failure shows an error dialog, with its own message for a scene over the size limit.
_reconcileElementsexcalidraw-app/collab/Collab.tsx:7725.1Restores incoming remote elements, merges them into the local scene and bumps versions, recording the resulting scene version so the merge is not broadcast back.
decryptPayloadexcalidraw-app/collab/Collab.tsx:4695.1Decrypts an incoming socket message with the room key and parses its JSON. On failure it alerts the user and returns an invalid-response marker.
syncElementsexcalidraw-app/collab/Collab.tsx:9825.1Called on every local change while collaborating: broadcasts the changed elements to peers and queues a Firestore save.
broadcastElementsexcalidraw-app/collab/Collab.tsx:9715.1Sends an update to peers when the scene version is newer than the last one sent or received, then schedules the throttled full-scene rebroadcast.
broadcastSceneexcalidraw-app/collab/Portal.tsx:1425.1Picks the elements whose version changed since they were last sent (or all of them on a full sync) and sends them to the room as an init or update message.
_broadcastSocketDataexcalidraw-app/collab/Portal.tsx:855.1Encrypts a message with the room key and emits it to the room over Socket.IO, on the volatile channel when the caller asks for it.
saveToFirebaseexcalidraw-app/data/firebase.ts:1905.1Writes the room's scene to its Firestore document in collection scenes, inside a transaction that decrypts the stored scene, reconciles it with the local elements and writes the re-encrypted result. Skips the write when this scene version is already saved.
loadFromFirebaseexcalidraw-app/data/firebase.ts:2525.1Reads the room's Firestore document, decrypts and restores its elements, and records that scene version as saved.
saveFilesToFirebaseexcalidraw-app/data/firebase.ts:1445.1Uploads encrypted image files to Firebase Storage under a path prefix with a cache max-age of 31,536,000 s, and reports which files saved and which failed.
createFirebaseSceneDocumentexcalidraw-app/data/firebase.ts:1765.1Builds the Firestore document for a scene: its scene version plus the encrypted elements and IV as Firestore bytes.
encryptElementsexcalidraw-app/data/firebase.ts:925.1Serialises elements to JSON and encrypts them with the room key, returning the ciphertext and IV.
decryptElementsexcalidraw-app/data/firebase.ts:1035.1Decrypts a stored Firestore scene with the room key and parses its elements.
reconcileElementspackages/excalidraw/data/reconcile.ts:735.1Merges remote elements into local ones element by element, keeping the local copy when it is being edited or is newer, and returns the merged list in order.
restoreElementspackages/excalidraw/data/restore.ts:9605.1Normalises elements from any source (a file, storage, a peer): fills in missing or legacy properties and de-duplicates ids. Optionally repairs bindings, refreshes text dimensions and drops invisible elements.
serializeAsJSONpackages/excalidraw/data/json.ts:525.1Serialises a scene to the .excalidraw JSON format, keeping only the app state fields meant for the target (a local file or the database).
compressDatapackages/excalidraw/data/encode.ts:3225.1Compresses a buffer with pako and encrypts it with AES-GCM under the given key, packing the encoding metadata, IV and content into one buffer.
decompressDatapackages/excalidraw/data/encode.ts:3745.1Unpacks a buffer made by compressData, decrypts it with the key and inflates the content and its metadata.
encryptDatapackages/excalidraw/data/encryption.ts:505.1Encrypts data with AES-GCM under a 128-bit key and a fresh 12-byte IV, returning the ciphertext and the IV.
decryptDatapackages/excalidraw/data/encryption.ts:805.1Decrypts AES-GCM ciphertext with the given IV and key.
Apppackages/excalidraw/components/App.tsx:5935.2The editor's class component: owns the scene, app state, history and action manager, renders the canvases and UI, and handles every input event.
handleCanvasPointerDownpackages/excalidraw/components/App.tsx:75475.2Starts any pointer interaction on the canvas (panning, selection, text, freedraw, linear elements or shape creation, depending on the active tool) and installs the move and up handlers for it.
createGenericElementOnPointerDownpackages/excalidraw/components/App.tsx:88355.2Creates a rectangle, diamond, ellipse, embeddable or sticky note at the grid-snapped pointer origin with the current style settings, and makes it the element being drawn.
newElementpackages/element/src/newElement.ts:1765.2Constructs a generic shape element from the given options, assigning it a new id, seed and version.
StaticCanvaspackages/excalidraw/components/canvases/StaticCanvas.tsx:335.2React component that owns the canvas the elements are drawn on, sizes it to the viewport and pixel ratio, and redraws it through renderStaticScene when the scene or view changes.
renderStaticScenepackages/excalidraw/renderer/staticScene.ts:6605.2Renders the element layer (background, grid, visible elements and frames), either at once or throttled to animation frames.
renderElementpackages/element/src/renderElement.ts:10255.2Draws one element on a canvas context, applying its opacity and offset, and hands the type-specific work to drawElement.
drawElementpackages/element/src/renderElement.ts:10735.2Switches on element type (frames, freedraw, images, text, shapes). On screen it draws from a cached per-element canvas; when exporting it draws vectors directly.
drawElementOnCanvaspackages/element/src/renderElement.ts:4605.2Paints an element's geometry onto a context: sticky notes, rough.js shapes, freedraw paths, images and text lines.
generateElementShapepackages/element/src/shape.ts:1245.2The ShapeCache's shape lookup: returns the element's rough.js drawable from a WeakMap cache, generating and caching it on a miss.
InteractiveCanvaspackages/excalidraw/components/canvases/InteractiveCanvas.tsx:865.2React component for the overlay canvas, which redraws selections, handles, remote cursors and snap lines through renderInteractiveScene.
renderInteractiveScenepackages/excalidraw/renderer/interactiveScene.ts:21585.2Renders the interactive layer (selection outlines, transform handles, collaborator cursors, snapping guides) and passes the result to the caller's callback.
exportToCanvaspackages/excalidraw/scene/export.ts:8385.2Renders a scene onto a new canvas for image export, sized to the content plus padding, painting it through renderStaticScene.

6. Boundary-crossing flows

Excalidraw runs as one browser tab. Nearly everything it does (drawing, undo, the store and history, saving to the browser) happens on one thread with no boundary crossed, and is left to the call graph in §5. This section covers only the six flows that leave the tab: they reach a server over HTTP or a WebSocket, another window through window messages, or another tab of the same origin through localStorage. Every server named here sits outside this repository (§1: the repository contains no server code), so the diagrams show each one as an opaque participant and draw only what the browser sends and receives.

The first four flows have sequence diagrams. Tab synchronisation and library install and publish are single request-and-response exchanges or a shared key read, so they appear as table rows only.

FlowBoundary crossedTransportWhat is encryptedWhere
Share linkBrowser to the share-link JSON backend (VITE_APP_BACKEND_V2_POST_URL, VITE_APP_BACKEND_V2_GET_URL) and to Firebase StorageHTTPS POST and GET; Firebase Storage SDK uploadScene and images, AES-GCM with a fresh 128-bit key per link. The key stays in the URL fragment #json=<id>,<key>excalidraw-app/data/index.ts:202-302
Live collaborationBrowser to the collaboration server (VITE_APP_WS_SERVER_URL), to every peer in the room, and to Firestore and StorageSocket.IO (WebSocket, falling back to polling); Firestore transaction; Storage uploadEvery socket payload and the stored scene, AES-GCM with the room key from #room=<roomId>,<roomKey>. The server sees room ids and ciphertextexcalidraw-app/collab/Collab.tsx:492-723
Excalidraw+ iframe exportThe editor in a hidden iframe at /excalidraw-plus-export to its parent window on VITE_APP_PLUS_APPCross-origin window messagesNothing. The scene is posted in plaintext, but only to the Excalidraw+ origin and only after an RS256 JWT verifiesexcalidraw-app/ExcalidrawPlusIframeExport.tsx:89-217
AI diagram generationBrowser to the AI backend (VITE_APP_AI_BACKEND)HTTPS POST with a streamed text/event-stream responseNothing end to end. Prompts, frame image and frame text go in plaintext over TLSexcalidraw-app/components/AI.tsx:21-190
Tab synchronisationOne tab to the other tabs of the same originlocalStorage version keys version-dataState and version-files, read when a tab gains focus or becomes visibleNothing. Same-origin browser storageexcalidraw-app/data/tabSync.ts, excalidraw-app/App.tsx:597-683
Library install and publishBrowser to the library host named in #addLibrary (checked against ALLOWED_LIBRARY_URLS) and to VITE_APP_LIBRARY_BACKEND/submitHTTPS GET for install; HTTPS multipart POST for publishNothing. Libraries are public by purpose, and the publish form carries the author's name and handlespackages/excalidraw/data/library.ts:497-540 and 718-740, packages/excalidraw/components/PublishLibrary.tsx:300-330

Share link

When a user creates a shareable link, exportToBackend generates a new key, serialises the scene, then compresses and encrypts it with compressData. It posts the ciphertext to the JSON backend, which answers with an id. The browser then uploads each image, encrypted by encodeFilesForUpload with the same key and capped at FILE_UPLOAD_MAX_BYTES (4 MiB), through saveFilesToFirebase to files/shareLinks/{id}/{fileId}. The returned URL carries #json=<id>,<key>. The key lives in the fragment, so the browser never sends it to any server. On the receiving side, initializeScene matches the fragment, importFromBackend downloads the ciphertext and decompressData decrypts it, and the images are fetched from Storage and decrypted in the same way.

Sender's browser JSON backend Firebase Storage Recipient's browser process boundary: every arrow below leaves the tab over https exportToBackend: new 128-bit key, compressData (AES-GCM) POST ciphertext { id } saveFilesToFirebase: encrypted images to files/shareLinks/{id}/{fileId} link = origin + #json=<id>,<key> (fragment never sent) link passed out of band (chat, email) initializeScene matches #json= importFromBackend: GET id ciphertext decompressData with key from fragment GET image files encrypted files, decrypted in browser
Figure 6.1 · share link export and importThe two servers hold only ciphertext and an id. The key crosses no server boundary: it moves in the link, from person to person.

Live collaboration

startCollaboration either reuses the room id and key from a #room= link or creates new ones with generateCollaborationLinkData, which takes the room id from generateRoomId (10 random bytes) and the key from generateEncryptionKey. It loads socket.io-client lazily and connects to VITE_APP_WS_SERVER_URL. The server emits init-room, and the client answers join-room with the room id. If the user is first in the room, the server emits first-in-room and initializeRoom loads the scene from Firestore with loadFromFirebase. If peers are present, the server emits new-user to each of them, and each one sends its whole scene as SCENE_INIT through broadcastScene.

Every payload is encrypted with encryptData under the room key before it is emitted as server-broadcast (or server-volatile-broadcast for cursors, idle status and viewport bounds). The receiving client decrypts client-broadcast messages with decryptPayload. On each local change, syncElements calls broadcastElements, which sends only the elements whose version moved (SCENE_UPDATE). queueBroadcastAllElements rebroadcasts the full scene and queueSaveToFirebase saves it through saveCollabRoomToFirebase and saveToFirebase, each throttled to SYNC_FULL_SCENE_INTERVAL_MS (20,000 ms). saveToFirebase runs a Firestore transaction that decrypts the stored scene, reconciles it with the local elements and writes the re-encrypted result. Images go to files/rooms/{roomId}/{fileId} through queueFileUpload, and peers pull them with fetchImageFilesFromFirebase. A joiner who gets no SCENE_INIT within INITIAL_SCENE_UPDATE_TIMEOUT (5,000 ms), or whose socket raises connect_error, falls back to initializeRoom and loads the room from Firestore. stopCollaboration closes the socket and resumes local saving.

Joining browser Collaboration serverSocket.IO, external Peer browser Firestore scenes/{roomId} startCollaboration: room id and key from #room= connect (websocket, polling) init-room join-room roomId new-user server-broadcast: SCENE_INIT (encrypted) client-broadcast (ciphertext, iv) decryptPayload, reconcile, render alt: first in room, connect_error, or no SCENE_INIT within 5,000 ms initializeRoom: loadFromFirebase (get document) sceneVersion, iv, ciphertext loop: while the session lasts SCENE_UPDATE: changed elements only client-broadcast volatile: cursor 33 ms, IDLE_STATUS every 20,000 ms: full-scene rebroadcast every 20,000 ms: saveToFirebase transaction (re-encrypted)
Figure 6.2 · live collaboration sessionThree boundaries: the socket server relays ciphertext it cannot read, peers decrypt with the key from their own link, and Firestore keeps the latest encrypted scene for anyone who joins when no peer answers.

Excalidraw+ iframe export

Excalidraw+ loads /excalidraw-plus-export in a hidden iframe to move a user's local scene into their Excalidraw+ account. ExcalidrawPlusIframeExport renders nothing. It posts READY to its parent window, addressed to the VITE_APP_PLUS_APP origin. Its handleMessage listener rejects any message whose origin is not VITE_APP_PLUS_APP. On REQUEST_SCENE it requires a JWT and checks it with verifyJWT against VITE_APP_PLUS_EXPORT_PUBLIC_KEY. parseSceneData then reads the scene from localStorage and the image files from IndexedDB, and the listener posts SCENE_DATA back to that one origin. Any failure is posted back as ERROR.

Excalidraw+ parent windowVITE_APP_PLUS_APP origin Editor iframe/excalidraw-plus-export cross-origin window boundary READY (targetOrigin = Plus) REQUEST_SCENE { jwt } 1. event.origin === VITE_APP_PLUS_APP, else throw 2. verifyJWT: RSASSA-PKCS1-v1_5, SHA-256, exp 3. parseSceneData: localStorage + IndexedDB SCENE_DATA { elements, appState, files } or ERROR { message }
Figure 6.3 · Excalidraw+ export handshakeThe scene leaves only for one origin and only on a request signed with the Excalidraw+ private key. A message from any other origin is rejected before it is read.

AI diagram generation

Two AI features call VITE_APP_AI_BACKEND, both wired in AIComponents. Text-to-diagram sends the chat messages to /v1/ai/text-to-diagram/chat-streaming through TTDStreamFetch. It reads the server-sent event stream chunk by chunk, reports rate limits, and honours an abort signal. Diagram-to-code starts in the editor's onMagicFrameGenerate. The app's plugin exports the frame as a JPEG and posts it, with the text of the frame's children, to /v1/ai/diagram-to-code/generate-streaming. Partial HTML is streamed into the pending iframe, and the generation then ends as done or error (§7). Neither request is end-to-end encrypted. A 429 response is shown to the user as a "too many requests" message.

Browser (AIComponents) AI backendVITE_APP_AI_BACKEND https, plaintext body POST /v1/ai/text-to-diagram/chat-streaming { messages } or POST /v1/ai/diagram-to-code/generate-streaming { texts, image } data: chunk ... (text/event-stream) data: chunk ... end of stream, or 429 / error
Figure 6.4 · AI streaming requestsThe only flow in which drawing content leaves the browser readable by a server operator: the frame image and its text, or the user's prompt.

Tab synchronisation

When one tab saves to browser storage, updateBrowserStateVersion writes the current time to version-dataState or version-files. When another tab regains focus or becomes visible, its visibilityChange listener runs the debounced syncData. syncData asks isBrowserStorageStateNewer whether either key is newer than this tab's own copy, and if so reloads the scene, library and missing images from storage. It does nothing while the tab is collaborating. On blur or hide, the same listener flushes the pending local save, so the other tab sees it.

Library install and publish

A link carrying #addLibrary=<url> is read by parseLibraryTokensFromUrl, then useHandleLibrary runs importLibraryFromURL. That function checks the URL with validateLibraryUrl against ALLOWED_LIBRARY_URLS (excalidraw.com and raw.githubusercontent.com/excalidraw/excalidraw-libraries), downloads it, and merges the items into the library, asking the user first unless the link carries this editor's own token. Publishing goes the other way. The Publish Library dialog posts the library file, a preview image, and the author's name, GitHub and Twitter handles and website as multipart form data to VITE_APP_LIBRARY_BACKEND/submit, which answers with a URL for the submission.

Functions named in this section

Functions in the boundary-crossing flows 41 rows
FunctionWhereWhat it does
exportToBackendexcalidraw-app/data/index.ts:248Encrypts the scene with a new key, posts it to the JSON backend and uploads its images to Storage. Returns the share URL with the id and key in the fragment, or an error message.
importFromBackendexcalidraw-app/data/index.ts:202Downloads a shared scene by id from the JSON backend and decrypts it with the key from the link. Falls back to the legacy format if the new one fails to decode.
initializeSceneexcalidraw-app/App.tsx:217Decides at load time where the first scene comes from: a #json= share link, a #url= link, a #room= collaboration link, or local storage.
compressDatapackages/excalidraw/data/encode.ts:322Compresses a buffer and encrypts it with the given key, packing metadata and IV into one binary blob.
decompressDatapackages/excalidraw/data/encode.ts:374Reverses compressData: splits the blob, decrypts it with the key and inflates the result.
encodeFilesForUploadexcalidraw-app/data/FileManager.ts:228Compresses and encrypts each image file for upload and rejects any file over the byte cap.
saveFilesToFirebaseexcalidraw-app/data/firebase.ts:144Uploads encoded files to Firebase Storage under a prefix with a cache max-age of 31,536,000 s. Reports which files were saved and which failed.
startCollaborationexcalidraw-app/collab/Collab.tsx:492Opens a collaboration session: picks or creates the room id and key, connects the Socket.IO client and registers the socket handlers. Arms the 5,000 ms fallback to Firestore.
generateCollaborationLinkDataexcalidraw-app/data/index.ts:148Creates a new room id and a new room encryption key for a session started from scratch.
generateRoomIdexcalidraw-app/data/index.ts:68Fills 10 bytes from window.crypto.getRandomValues and returns them as hex.
generateEncryptionKeypackages/excalidraw/data/encryption.ts:12Generates a 128-bit AES-GCM key with Web Crypto and returns it as a JWK string or a key object.
initializeRoomexcalidraw-app/collab/Collab.tsx:725Cancels the fallback timer and, when asked to fetch, loads and decrypts the room's scene from Firestore. Then marks the socket initialised.
loadFromFirebaseexcalidraw-app/data/firebase.ts:252Reads the scenes/{roomId} document and decrypts its elements with the room key. Records the scene version against the socket.
broadcastSceneexcalidraw-app/collab/Portal.tsx:142Sends the scene, or only elements whose version advanced, to the room as an encrypted SCENE_INIT or SCENE_UPDATE. Queues pending image uploads.
encryptDatapackages/excalidraw/data/encryption.ts:50Encrypts a buffer with AES-GCM under the given key and a fresh 12-byte IV, returning both.
decryptDatapackages/excalidraw/data/encryption.ts:80Decrypts an AES-GCM buffer with the given IV and key.
decryptPayloadexcalidraw-app/collab/Collab.tsx:469Decrypts an incoming socket message with the room key and parses it as JSON.
syncElementsexcalidraw-app/collab/Collab.tsx:982Called on every local scene change while collaborating: broadcasts the change and queues a throttled Firestore save.
broadcastElementsexcalidraw-app/collab/Collab.tsx:971Sends a SCENE_UPDATE when the scene version is newer than the last one sent or received, then queues the full rebroadcast.
queueBroadcastAllElementsexcalidraw-app/collab/Collab.tsx:987Throttled to 20,000 ms: rebroadcasts every element, including deleted ones, so peers repair any dropped update.
queueSaveToFirebaseexcalidraw-app/collab/Collab.tsx:1001Throttled to 20,000 ms on the trailing edge: saves the room's scene to Firestore once the socket is initialised.
saveCollabRoomToFirebaseexcalidraw-app/collab/Collab.tsx:334Calls saveToFirebase and applies the reconciled scene that comes back. On failure it shows an error dialog once per message and an error indicator.
saveToFirebaseexcalidraw-app/data/firebase.ts:190In a Firestore transaction, decrypts the stored scene, reconciles it with the local elements and writes the re-encrypted result. Skips the write if this version is already saved.
queueFileUploadexcalidraw-app/collab/Portal.tsx:104Throttled to 300 ms: uploads pending images to Storage and marks their elements saved, which tells peers to fetch them.
fetchImageFilesFromFirebaseexcalidraw-app/collab/Collab.tsx:441Downloads and decrypts the room's images that the local scene references but has not loaded yet.
stopCollaborationexcalidraw-app/collab/Collab.tsx:376Ends the session: cancels the queued broadcast and save, saves once more to Firestore, then closes the socket and resets the local storage versions. Marks saved images pending again so local storage re-saves them.
ExcalidrawPlusIframeExportexcalidraw-app/ExcalidrawPlusIframeExport.tsx:153The component rendered at /excalidraw-plus-export. It posts READY to the Excalidraw+ parent and installs the message listener that answers scene requests.
handleMessageexcalidraw-app/ExcalidrawPlusIframeExport.tsx:157Rejects messages from any origin other than VITE_APP_PLUS_APP. Answers a REQUEST_SCENE with a verified JWT with the scene, or with an ERROR.
verifyJWTexcalidraw-app/ExcalidrawPlusIframeExport.tsx:89Verifies the token's RSASSA-PKCS1-v1_5 SHA-256 signature against the configured public key and rejects it if exp has passed.
parseSceneDataexcalidraw-app/ExcalidrawPlusIframeExport.tsx:42Parses the elements and app state saved in localStorage and loads the images they reference from IndexedDB. Throws if the scene is empty.
AIComponentsexcalidraw-app/components/AI.tsx:21Wires the diagram-to-code plugin and the text-to-diagram dialog to the AI backend URLs and the IndexedDB chat store.
TTDStreamFetchpackages/excalidraw/components/TTDDialog/utils/TTDStreamFetch.ts:84Posts chat messages to a streaming endpoint and parses the server-sent data: lines into chunks. Returns the generated text, rate-limit figures or an error.
onMagicFrameGeneratepackages/excalidraw/components/App.tsx:2879Collects a magic frame's children, inserts an iframe next to it, and calls the diagram-to-code plugin. Streams partial HTML into the iframe and records done or error.
updateBrowserStateVersionexcalidraw-app/data/tabSync.ts:17Writes the current time to a localStorage version key and remembers it as this tab's own version.
isBrowserStorageStateNewerexcalidraw-app/data/tabSync.ts:12Returns true when the version key in localStorage is newer than the one this tab last wrote or read.
syncDataexcalidraw-app/App.tsx:597Debounced to 50 ms: when the tab is visible and not collaborating, reloads the scene, library, username and missing images that another tab saved more recently.
visibilityChangeexcalidraw-app/App.tsx:660Flushes the pending local save on blur or hide, and runs syncData on focus or when the tab becomes visible.
parseLibraryTokensFromUrlpackages/excalidraw/data/library.ts:530Reads the addLibrary URL and optional token from the hash, or from the legacy query string.
useHandleLibrarypackages/excalidraw/data/library.ts:677React hook that watches the URL for library links and runs the install, and that loads and saves the library through the host's adapter.
importLibraryFromURLpackages/excalidraw/data/library.ts:718Validates a library URL, downloads it and merges its items into the library, prompting first unless the link's token matches this editor.
validateLibraryUrlpackages/excalidraw/data/library.ts:497Accepts a URL only if its hostname ends with, and its path starts with, an entry in ALLOWED_LIBRARY_URLS or the host's own validator. Throws otherwise.

7. State machines

Three things in the code are genuine state machines: a value that takes one of a few named states, with named transitions and code that makes each one. They are the collaborator idle state, the image element status and the diagram-to-code generation status. Each has a small figure and a transition table (from, to, trigger, where). There are 12 transitions in all.

Three other candidates are deliberately not drawn. appState.activeTool is a value that any tool can be set to from any other tool; it has no named transitions, so a diagram would invent structure. The collaboration session is a boolean (isCollaboratingAtom) plus a socket that is either open or not. Its interesting sequencing is the connect, join and fallback exchange, which is a boundary-crossing flow and is drawn in §6 as Figure 6.2. The text-to-diagram chat keeps a list of messages and a streaming flag, not a set of named states, so it is described in §6 and not here.

Collaborator idle state

While a collaboration session is open, each client reports whether its user is active, idle or away (the UserIdleState enum). Every report goes to the room as a volatile, encrypted IDLE_STATUS message through onIdleStateChange and broadcastIdleChange, and peers show it on that user's avatar. initializeIdleDetector installs the two listeners that drive it, one for pointer move and one for visibility change. Two timers do the rest: IDLE_THRESHOLD (60,000 ms) without a pointer move makes the user idle, and while the user is active the state is re-announced every ACTIVE_THRESHOLD (3,000 ms).

active idle away 60,000 ms, no pointer move pointer move tab hidden (from active or idle) tab visible again every 3,000 ms
Figure 7.1 · collaborator idle stateThe state lives in each client and crosses to peers only as a volatile broadcast. A peer never computes it: it shows whatever the last IDLE_STATUS it received says.

Image element status

An image element carries status: "pending" | "saved" | "error" (packages/element/src/types.ts:166). The status records whether the image's file is stored where the current session keeps files. It is also how collaborators learn that a file is ready to fetch: an element that turns saved tells peers to pull the image. newImageElement creates every image as pending, and restoring a scene treats a missing status as pending. Once the file is stored (in IndexedDB by the local save, or in Firebase Storage by queueFileUpload during a session), shouldUpdateImageElementStatus picks out the pending elements and they become saved. Starting or stopping a session changes where files must live, so every saved image is set back to pending and stored again. updateStaleImageStatuses marks an image error when its file cannot be loaded. No code path moves an element out of error.

pending saved error inserted file stored (IndexedDB or Storage) session starts or stops file cannot be loaded
Figure 7.2 · image element statusThe status is part of the synced element, so a transition made by one browser is a signal to every other: saved means "the file is up, fetch it".

Diagram-to-code generation

Each diagram-to-code request inserts a new iframe element next to the magic frame and tracks it in MagicGenerationData, which is pending, done (with the generated HTML) or error (with a code and message). onMagicFrameGenerate sets the state and updateMagicGeneration stores it. pending is kept in memory only. done and error are also written to the iframe element's customData.generationData, so they are saved with the scene. While the state is pending, partial HTML from the stream is fed into the iframe; once it leaves pending, further partial chunks are ignored. A new generation creates a new iframe, so no transition leaves done or error. An iframe found with no generation data at all is rendered as an error (ERR_NO_GENERATION_DATA).

pendingin memory only donehtml saved in customData errorcode, message request starts HTML received empty result or request fails
Figure 7.3 · diagram-to-code generationOnly the end states persist. A scene saved mid-generation reloads with no generation data and shows the error placeholder.

Transitions

MachineFromToTriggerWhere
Collaborator idle stateactiveidleIDLE_THRESHOLD (60,000 ms) passes with no pointer move; reportIdle broadcasts idle and stops the active heartbeatexcalidraw-app/collab/Collab.tsx:869
Collaborator idle stateidleactivePointer move: onPointerMove restarts the idle timer and the reportActive interval, so active is broadcast within 3,000 msexcalidraw-app/collab/Collab.tsx:832
Collaborator idle stateactive or idleawayThe tab is hidden: onVisibilityChange clears both timers and broadcasts awayexcalidraw-app/collab/Collab.tsx:848-858
Collaborator idle stateawayactiveThe tab is visible again: onVisibilityChange restarts both timers and broadcasts activeexcalidraw-app/collab/Collab.tsx:859-865
Collaborator idle stateactiveactiveRe-announced every ACTIVE_THRESHOLD (3,000 ms) by reportActive while the pointer keeps movingexcalidraw-app/collab/Collab.tsx:877
Image element status(new)pendingAn image is inserted (newImageElement), or a scene is restored with no status on an imagepackages/element/src/newElement.ts:706, packages/excalidraw/data/restore.ts:621
Image element statuspendingsavedThe file is stored: in IndexedDB by the local save callback, or in Firebase Storage by queueFileUpload during a sessionexcalidraw-app/App.tsx:737, excalidraw-app/collab/Portal.tsx:129
Image element statussavedpendingA collaboration session starts (startCollaboration) or stops (stopCollaboration), so every file is stored again in its new homeexcalidraw-app/collab/Collab.tsx:565 and 412
Image element statuspending or savederrorThe file cannot be loaded from IndexedDB or Firebase: updateStaleImageStatusesexcalidraw-app/data/FileManager.ts:272
Diagram-to-code generation(new)pendingA generation starts from the frame's button or from upstream: onMagicFrameGenerate inserts the iframe and records pendingpackages/excalidraw/components/App.tsx:2919-2922
Diagram-to-code generationpendingdoneThe plugin returns non-empty HTML; it is trimmed to the document and storedpackages/excalidraw/components/App.tsx:2973-2984
Diagram-to-code generationpendingerrorThe plugin returns empty HTML, or the request throwspackages/excalidraw/components/App.tsx:2962-2969 and 2985-2993

Functions named in this section

FunctionWhereWhat it does
initializeIdleDetectorexcalidraw-app/collab/Collab.tsx:881Adds the document's pointer-move and visibility-change listeners that drive the idle state, when a session starts.
onPointerMoveexcalidraw-app/collab/Collab.tsx:832Restarts the 60,000 ms idle timer on every pointer move, and starts the 3,000 ms active heartbeat if it is not running.
onVisibilityChangeexcalidraw-app/collab/Collab.tsx:848Broadcasts away and stops both timers when the tab is hidden. Restarts them and broadcasts active when it is shown.
reportIdleexcalidraw-app/collab/Collab.tsx:869Broadcasts idle and stops the active heartbeat.
reportActiveexcalidraw-app/collab/Collab.tsx:877Broadcasts active. It runs on the 3,000 ms interval.
onIdleStateChangeexcalidraw-app/collab/Collab.tsx:967Hands a new idle state to the portal for broadcast.
broadcastIdleChangeexcalidraw-app/collab/Portal.tsx:185Sends the user's idle state, socket id and username to the room as a volatile, encrypted IDLE_STATUS message.
newImageElementpackages/element/src/newElement.ts:692Creates an image element with its file id, scale and crop. Its status is pending unless one is given.
shouldUpdateImageElementStatusexcalidraw-app/data/FileManager.ts:202Returns true for an initialised image element that is still pending and whose file this manager has saved.
queueFileUploadexcalidraw-app/collab/Portal.tsx:104Throttled to 300 ms: uploads pending images to Storage and marks their elements saved. A failure other than an abort is shown as an error message.
startCollaborationexcalidraw-app/collab/Collab.tsx:492Opens a collaboration session. When it creates a new room, it marks saved images pending so they upload to the room's Storage path.
stopCollaborationexcalidraw-app/collab/Collab.tsx:376Ends the session and marks saved images pending, so the local store saves them again.
updateStaleImageStatusesexcalidraw-app/data/FileManager.ts:272Sets status: "error" on every image element whose file failed to load, without recording an undo step.
onMagicFrameGeneratepackages/excalidraw/components/App.tsx:2879Inserts an iframe beside a magic frame, records the generation as pending, and calls the diagram-to-code plugin. Records done with the HTML, or error.
updateMagicGenerationpackages/excalidraw/components/App.tsx:2837Stores a generation state in memory and re-renders. It also writes done and error, but not pending, to the iframe element's custom data.

8. Security model

The security design rests on one choice. The browser is the only place a drawing exists in readable form, and the servers it talks to are treated as untrusted storage and relays. Scenes shared by link or by collaboration are encrypted in the browser with AES-GCM, a 128-bit key (ENCRYPTION_KEY_BITS = 128) and a 12-byte IV. The key travels only in the URL fragment (#json=<id>,<key> for share links, #room=<roomId>,<roomKey> for collaboration), and browsers do not send the fragment to servers. Error reports follow the same rule: Sentry's beforeSend strips the fragment from the reported URL. The repository contains no server code, so every server control in this section is either a rules file kept here (Firebase) or something this repository cannot show.

Browser tab (trusted) plaintext scene, room and link keys localStorage, IndexedDB encryptData / decryptData key only in URL fragment Collaboration serverroom ids and ciphertext only Share-link JSON backendciphertext only Firestore and Storageciphertext, rules: get and write if true AI backendplaintext image and text Excalidraw+ parent windoworigin check + RS256 JWT Embedded iframessandbox; messages from 2 origins URL-supplied inputs#url= open; #addLibrary allowlisted CI and release pipelinebuilds the bundle every user runs red: a boundary where the control is weaker than the encryption model around it
Figure 8.1 · trust boundariesThe trusted zone is one browser tab. Three backends see only ciphertext. The AI backend sees plaintext. The parent window and embeds are reached through checked window messages. URL inputs and the build pipeline feed code and data into the tab.

Trust boundaries

BoundaryWhat crosses itThe controlWhere
Browser to collaboration server (VITE_APP_WS_SERVER_URL)Room ids, socket ids and AES-GCM ciphertext of every scene update, cursor, idle status and viewport messagePayloads are encrypted with the room key before emit, so the server relays what it cannot read. The server itself is not in this repositoryexcalidraw-app/collab/Portal.tsx:85-100
Browser to share-link JSON backendCompressed, encrypted scene; the backend returns an idA fresh key per link, kept in the fragment. The backend holds ciphertext addressed by idexcalidraw-app/data/index.ts:248-302
Browser to Firebase Firestore and StorageEncrypted room scene (scenes/{roomId}: sceneVersion, iv, ciphertext) and encrypted image filesCiphertext only, under open rules: firestore.rules allows get and write to anyone and denies list; storage.rules allows get and write on the rooms and shareLinks paths. Nothing in the repository deploys these rulesfirebase-project/firestore.rules, firebase-project/storage.rules
Browser to AI backend (VITE_APP_AI_BACKEND)Plaintext frame image (JPEG data URL) and text, or the text-to-diagram chat messagesTLS only, no end-to-end encryption. The backend applies its own rate limit (429)excalidraw-app/components/AI.tsx:55-180
Editor to the Excalidraw+ parent windowThe local scene and its images, as SCENE_DATAMessages from any origin other than VITE_APP_PLUS_APP are rejected. A request needs a JWT that verifyJWT checks with RSASSA-PKCS1-v1_5 SHA-256 (RS256) against VITE_APP_PLUS_EXPORT_PUBLIC_KEY, with exp checked when present. Replies are addressed to that origin onlyexcalidraw-app/ExcalidrawPlusIframeExport.tsx:89-217
Editor to embedded iframesThird-party pages and generated HTML rendered inside the canvas, and window messages back from themEach iframe is sandboxed (scripts, forms and popups allowed; same-origin only for the video hosts in ALLOW_SAME_ORIGIN). Embeddable links are checked by embeddableURLValidator. onWindowMessage accepts messages only from https://player.vimeo.com and https://www.youtube.compackages/excalidraw/components/App.tsx:1117 and 2066-2088, packages/element/src/embeddable.ts:139-569
URL-supplied inputsA scene from #url=; a library from #addLibrary=#url= downloads any URL the link names, with no allowlist, and asks for confirmation only when the current canvas is not empty. #addLibrary is checked by validateLibraryUrl against ALLOWED_LIBRARY_URLS (excalidraw.com and raw.githubusercontent.com/excalidraw/excalidraw-libraries)excalidraw-app/App.tsx:231 and 303-320, packages/excalidraw/data/library.ts:54-58 and 497-540
CI and release pipelineSource to the npm packages, the Docker image and the Sentry release; GitHub secrets into jobsSecrets are held as GitHub secrets, no secret value is committed, and every third-party action is pinned to a commit SHA. The Sentry release job installs sentry-cli by piping https://sentry.io/get-cli/ to bash, and the next step runs that binary with SENTRY_AUTH_TOKEN, SENTRY_ORG and SENTRY_PROJECT.github/workflows/sentry-production.yml:25-40

Authentication

There is none for users, by design. Excalidraw has no accounts, no login and no session token, so there is no identity source and no token lifetime. The only credential is the key in the URL fragment: whoever holds a link can read the scene, and in a collaboration room can also write to it. Firestore and Storage do not see that key. For them, possessing a room id is enough to overwrite a room's ciphertext. The room id is 10 random bytes (ROOM_ID_BYTES = 10, 80 bits) from window.crypto.getRandomValues, made by generateRoomId. A forged write cannot be read as a scene without the key, but it can replace or corrupt the room for everyone in it. The one authenticated exchange is the Excalidraw+ export, where the parent proves itself with a JWT signed by the Excalidraw+ private key.

Authorisation

Authorisation is enforced only by the Firebase rules, and they grant everything except enumeration. firestore.rules allows get, write: if true on every document and list: if false. The comment there says list stays denied so that nobody can delete anyone else's drawing, which works only because room ids cannot be listed or guessed. storage.rules allows get and write on files/rooms/{room}/{file} and files/shareLinks/{shareLink}/{file}. firestore.indexes.json declares no indexes. Nothing in the repository deploys these rules, so what is live in the Firebase project cannot be confirmed from here. The JSON backend, the collaboration server and the AI backend do their own authorisation, if any, outside this repository. When a check is missing, nothing in the browser stands behind it: the design relies on unguessable ids and on encryption, not on access control.

Deliberately public

Three values that look like secrets are public client configuration, committed on purpose and shipped in the bundle. The Sentry DSN is hard-coded in excalidraw-app/sentry.ts. The Firebase web config, including its apiKey, is in VITE_APP_FIREBASE_CONFIG; a Firebase web key identifies the project, and the rules above are what limit it. The Excalidraw+ RSA public keys are in VITE_APP_PLUS_EXPORT_PUBLIC_KEY in .env.production and .env.development. Also public: the endpoint URLs of every backend, inlined into the bundle at build time. One header is missing: vercel.json sets Access-Control-Allow-Origin, X-Content-Type-Options, Referrer-Policy and a Feature-Policy of *, but no Content-Security-Policy. Nothing in the repository sets a CSP for excalidraw.com or for the Docker image.

Flagged lines and install hooks

The evidence's outbound-call probe flagged four lines and one install hook. §12 reads each one in its "Install hook and risk-pattern lines" table. One of them bears on security: curl -sL https://sentry.io/get-cli/ | bash at .github/workflows/sentry-production.yml:25 installs whatever that URL serves at release time, unpinned and unverified, in a job whose next step runs the result with the Sentry secrets (the CI row of the table above). The two toast matches in actionExport.tsx:136 and LayerUI.tsx:693 are false positives, the ALLOWED_LIBRARY_URLS entry at library.ts:57 is benign, and prepare: husky install makes no network call.

Functions named in this section

FunctionWhereWhat it does
encryptDatapackages/excalidraw/data/encryption.ts:50Encrypts a buffer with AES-GCM under the given key and a fresh 12-byte IV, returning both.
decryptDatapackages/excalidraw/data/encryption.ts:80Decrypts an AES-GCM buffer with the given IV and key; it throws if the key is wrong or the data was altered.
beforeSendexcalidraw-app/sentry.ts:39Sentry hook run on every event before it is sent: it strips the URL fragment from the request URL and adds a stack trace to console errors.
generateRoomIdexcalidraw-app/data/index.ts:68Fills 10 bytes from window.crypto.getRandomValues and returns them as hex, giving an 80-bit room id.
verifyJWTexcalidraw-app/ExcalidrawPlusIframeExport.tsx:89Verifies a JWT's RSASSA-PKCS1-v1_5 SHA-256 signature with Web Crypto against the configured public key, ignoring the token's own algorithm header. It rejects the token if exp has passed.
onWindowMessagepackages/excalidraw/components/App.tsx:1117Drops window messages unless they come from https://player.vimeo.com or https://www.youtube.com. It answers a Vimeo player's pause event with a play or pause command, and records each YouTube player's playback state.
embeddableURLValidatorpackages/element/src/embeddable.ts:536Decides whether a link may be embedded, using the host's validateEmbeddable setting if one is given and the built-in domain allowlist otherwise.
validateLibraryUrlpackages/excalidraw/data/library.ts:497Accepts a library URL only if its hostname ends with, and its path starts with, an entry in ALLOWED_LIBRARY_URLS or the host's own validator. Throws otherwise.

Security rating

Security: 7/10, Good

Good. Shared scenes are end-to-end encrypted in the browser with the key kept in the URL fragment, so servers hold only ciphertext, and the Excalidraw+ export, embeds and library installs are each checked at their boundary; no secret is committed and actions and base images are pinned. The gaps a reader can name: open Firestore and Storage rules make the unguessable 80-bit room id the only guard on integrity, #url= fetches any URL, there is no Content-Security-Policy, AI requests send drawings in plaintext, and the Sentry release job pipes a remote script into bash in a job that holds secrets. The technical assessment gives the reasoning per criterion.

9. Configuration and secrets

Configuration is fixed at build time: Vite reads the committed root .env.development or .env.production (loadEnv(mode, '../')) and inlines every VITE_* value into the bundle, so the Docker image carries the production endpoints and cannot be pointed elsewhere without a rebuild. There is no .env.example; the committed .env files and the two vite-env.d.ts declarations are the reference. The read is at excalidraw-app/vite.config.mts:140. The npm package is built the same way by a different route: scripts/buildPackage.js calls parseEnvVariables on both .env files and passes the result to esbuild as the whole of import.meta.env (lines 93 and 103), so the published @excalidraw/excalidraw bundle also carries the values in the committed .env files.

The files themselves invite local overrides: .env.development tells a developer to put local flags in .env.local (line 19) or .env.development.local (line 54), and Vite merges those over the committed file, which is why .env.production sets the debug flags explicitly to false (its comment at line 29). A third file, .env.test, holds one variable for the Vitest run.

The evidence probe found 10 distinct variables, all in CI scripts and test set-up; it did not see the application's import.meta.env.VITE_* reads, the dev-server reads in vite.config.mts, or the template reads in excalidraw-app/index.html. The table below adds them from a search of the source for import.meta.env., process.env., envVars. and the EJS conditionals in index.html. Vite's own built-ins (MODE, DEV, PROD, BASE_URL) are read in a dozen places but are set by Vite, not by this repository, and are left out. Default gives the value in .env.development and in .env.production where they differ; "not set" means neither file assigns it.

This section counts 41 configuration variables and 8 CI secrets (NPM_TOKEN, SENTRY_AUTH_TOKEN, SENTRY_ORG, SENTRY_PROJECT, DOCKER_USERNAME, DOCKER_PASSWORD, PUSH_TRANSLATIONS_COVERAGE_PAT, GITHUB_TOKEN). No secret value is committed: the Firebase apiKey and the two Excalidraw+ RSA public keys in the .env files are public client configuration.

Five of the 41 are declared and never read. packages/excalidraw/vite-env.d.ts:33-35 declares VITE_APP_MATOMO_URL, VITE_APP_CDN_MATOMO_TRACKER_URL and VITE_APP_MATOMO_SITE_ID, which nothing sets or reads. FAST_REFRESH is set at .env.development:27 and declared at packages/excalidraw/vite-env.d.ts:30, and VITE_APP_PORTAL_URL is declared in both vite-env.d.ts files (excalidraw-app/vite-env.d.ts:15, packages/excalidraw/vite-env.d.ts:19). One more, CI_JOB_NUMBER, is set at .github/workflows/size-limit.yml:10 for the third-party size-limit action and read by no code in the repository.

Configuration variables 41 rows
VariableDefaultRead atWhat it controlsWhen absent
VITE_APP_BACKEND_V2_GET_URLdev https://json-dev.excalidraw.com/api/v2/; prod https://json.excalidraw.com/api/v2/excalidraw-app/data/index.ts:65Base URL the share-link scene is fetched from, with the scene id appended.The fetch goes to a relative path beginning "undefined" on the app's own origin and fails; opening a #json= link shows the "import failed" alert and an empty scene.
VITE_APP_BACKEND_V2_POST_URLdev https://json-dev.excalidraw.com/api/v2/post/; prod https://json.excalidraw.com/api/v2/post/excalidraw-app/data/index.ts:66URL the encrypted scene is posted to when a user creates a share link.fetch(undefined) requests the current page, the JSON parse fails, and creating a share link reports an error. Nothing fails until a user shares.
VITE_APP_WS_SERVER_URLdev http://localhost:3002; prod https://oss-collab.excalidraw.comexcalidraw-app/collab/Collab.tsx:545Socket.IO collaboration server (excalidraw-room) the room connects to.socket.io-client connects to the page's own origin, which has no Socket.IO endpoint; the connection errors and the room falls back to loading its scene from Firestore with no live sync.
VITE_APP_FIREBASE_CONFIGdev project excalidraw-oss-dev; prod project excalidraw-room-persistence (JSON with apiKey, authDomain, projectId, storageBucket, messagingSenderId, appId)excalidraw-app/data/firebase.ts:39Firebase app config for the Firestore scenes collection and the Storage files bucket.The JSON.parse fails, a console warning prints the supplied value, and the config falls back to {}; Firebase calls then fail when a room or share link first saves or loads files.
VITE_APP_AI_BACKENDdev http://localhost:3016; prod https://oss-ai.excalidraw.comexcalidraw-app/components/AI.tsx:67, 171Backend for text-to-diagram and diagram-to-code generation.Requests go to "undefined/v1/ai/..." on the app's origin and fail; the AI dialogs show an error.
VITE_APP_PLUS_LPhttps://plus.excalidraw.com (both)excalidraw-app/App.tsx:919; also AppMainMenu.tsx:47, AppSidebar.tsx:101, AI.tsx:100, AppWelcomeScreen.tsx:70, ChatMessage.tsx:88Excalidraw+ marketing site used in promotional links.Links point at "undefined/plus?..." and lead nowhere; nothing else breaks.
VITE_APP_PLUS_APPdev http://localhost:3000; prod https://app.excalidraw.comexcalidraw-app/ExcalidrawPlusIframeExport.tsx:16; also App.tsx:942, ExportToExcalidrawPlus.tsx:81, AppMainMenu.tsx:56Excalidraw+ app origin: the only origin the /excalidraw-plus-export iframe accepts messages from, and the target of export and sign-in links.No origin equals undefined, so the iframe export accepts no message and Excalidraw+ export cannot complete; links break.
VITE_APP_PLUS_EXPORT_PUBLIC_KEYan RSA public key, different in dev and prodexcalidraw-app/ExcalidrawPlusIframeExport.tsx:171Public key the export JWT is verified against before the scene is posted to Excalidraw+.Key import fails, every JWT is rejected and the iframe replies with an error; the scene is never released, so the failure is closed rather than open.
VITE_APP_LIBRARY_URLhttps://libraries.excalidraw.com (both)packages/excalidraw/components/LibraryMenuBrowseButton.tsx:21Public library site the "Browse libraries" button opens.The button opens "undefined?target=..."; browsing libraries breaks, installing from a known URL still works.
VITE_APP_LIBRARY_BACKENDhttps://us-central1-excalidraw-room-persistence.cloudfunctions.net/libraries (both)packages/excalidraw/components/PublishLibrary.tsx:318Cloud Function the "publish library" form posts to.The submit request fails and the publish dialog shows an error.
VITE_APP_ENABLE_TRACKINGdev true; prod false; build:app forces truepackages/excalidraw/analytics.ts:22Whether product events are forwarded to Simple Analytics.Anything but the string "true" turns tracking off. .env.production sets it to false, but the build:app script sets VITE_APP_ENABLE_TRACKING=true on the command line, so the Vercel build tracks.
VITE_WORKER_IDnot setpackages/excalidraw/analytics.ts:21When set, marks the code as running in a worker and suppresses tracking.The normal case: nothing in the repository sets it, so tracking depends only on the flag above.
VITE_APP_DISABLE_SENTRYnot set; build:app:docker sets trueexcalidraw-app/sentry.ts:11Turns Sentry error reporting off.Sentry starts when the hostname contains excalidraw.com, staging.excalidraw.com or vercel.app, and stays off elsewhere.
VITE_APP_GIT_SHAnot set; build:app copies VERCEL_GIT_COMMIT_SHA, stats.yml sets github.shaexcalidraw-app/index.tsx:12, excalidraw-app/sentry.ts:25Build commit, exposed as window.__EXCALIDRAW_SHA__ and used as the Sentry release.The global and the Sentry release are undefined; errors are reported without a release.
VITE_APP_DISABLE_PREVENT_UNLOADempty in dev; not set in prodexcalidraw-app/App.tsx:700, excalidraw-app/collab/Collab.tsx:324Developer switch that stops the "leave site?" prompt when files or a room have unsaved changes.The prompt is shown, which is the production behaviour.
VITE_APP_DEBUG_ENABLE_TEXT_CONTAINER_BOUNDING_BOXempty in dev; prod falsepackages/element/src/renderElement.ts:970Debug overlay that draws the bounding box of text inside containers.No overlay, the normal case.
PKG_NAMEpackage.json name, set by packages/excalidraw/env.cjs:13packages/excalidraw/fonts/ExcalidrawFontFace.ts:12Package name in the font fallback URL on esm.sh.Absent in the app build, by design: the fallback URL becomes the latest @excalidraw/excalidraw on esm.sh.
PKG_VERSIONpackage.json version, set by packages/excalidraw/env.cjs:14packages/excalidraw/fonts/ExcalidrawFontFace.ts:13Package version in the same fallback URL, so a published package loads its own fonts.Only read when PKG_NAME is set; absent with it in the app build.
VITE_APP_PORTdev 3001excalidraw-app/vite.config.mts:148Dev server port.Falls back to 3000.
VITE_APP_ENABLE_ESLINTdev true; prod false; stats.yml falseexcalidraw-app/vite.config.mts:291ESLint overlay in the dev server through the checker plugin.Only the string "false" disables it, so absent means ESLint runs.
VITE_APP_COLLAPSE_OVERLAYdev true; prod falseexcalidraw-app/vite.config.mts:295Whether the checker overlay starts collapsed.The overlay starts collapsed (only "false" opens it).
VITE_APP_ENABLE_PWAdev falseexcalidraw-app/vite.config.mts:305Service worker in the dev server.No service worker in development; production builds register it regardless.
VITE_APP_DEV_DISABLE_LIVE_RELOADempty in devexcalidraw-app/index.html:143Disables Vite live reload, for debugging service workers.Live reload stays on.
VITE_APP_PORTAL_URLnot setdeclared excalidraw-app/vite-env.d.ts:15, packages/excalidraw/vite-env.d.ts:19Declared and never read.No effect.
FAST_REFRESHdev false (.env.development:27)declared packages/excalidraw/vite-env.d.ts:30Declared and never read; a leftover from the pre-Vite build.No effect.
VITE_APP_MATOMO_URLnot setdeclared packages/excalidraw/vite-env.d.ts:33Declared and never read; analytics moved to Simple Analytics.No effect.
VITE_APP_CDN_MATOMO_TRACKER_URLnot setdeclared packages/excalidraw/vite-env.d.ts:34Declared and never read.No effect.
VITE_APP_MATOMO_SITE_IDnot setdeclared packages/excalidraw/vite-env.d.ts:35Declared and never read.No effect.
VERCEL_GIT_COMMIT_SHAset by Vercel at build timeexcalidraw-app/package.json:46Copied into VITE_APP_GIT_SHA by the build:app script.Outside Vercel the shell substitutes an empty string and the Sentry release is blank.
NODE_ENVDockerfile ARG production; docker-compose.yml developmentDockerfile:12, docker-compose.yml:6 and 15Build mode seen by the toolchain during yarn build:app:docker; no repository code reads it.The Dockerfile default, production, applies. The compose file overrides it to development at build and at run time, where nginx ignores it.
IS_PREACTset to "false" in codedev-docs/docusaurus.config.js:7Assigned so the package does not throw on a missing process.env inside Docusaurus; nothing in the repository reads it.Not applicable: the line always sets it.
VITE_DEBUG_DOM.env.test falsesetupTests.ts:24Whether testing-library failures include the full serialised DOM.Failures omit the DOM dump, the default.
OSS_STATS_API_URLnot setscripts/stats/post.mjs:30Stats backend the bundle and perf results are posted to.Falls back to https://backend.excalidraw.com.
OSS_STATS_TOKENGitHub secret, stats.yml:39 and 71scripts/stats/post.mjs:45Token sent in the x-oss-stats-token header.The script prints "OSS_STATS_TOKEN is not set" and exits 1, failing the stats job. The one variable checked before use.
GITHUB_SHAset by GitHub Actionsscripts/stats/post.mjs:56Commit the stats are recorded against, unless --commit is passed.Falls back to HEAD.
GITHUB_RUN_IDset by GitHub Actionsscripts/stats/post.mjs:62-63Builds the link to the workflow run stored with the stats.runUrl is null.
GITHUB_SERVER_URLset by GitHub Actionsscripts/stats/post.mjs:63Host part of the run link.Only read when GITHUB_RUN_ID is set; the link would read "undefined/...".
GITHUB_REPOSITORYset by GitHub Actionsscripts/stats/post.mjs:63Repository part of the run link.As above.
RUNNER_NAMEset by GitHub Actionsscripts/stats/perf.mjs:1094Runner recorded with each perf benchmark run.Recorded as null.
PR_TITLEgithub.event.pull_request.title.github/workflows/semantic-pr-title.yml:66Pull request title parsed for scopes that become s-app, s-editor or s-package labels.title.match throws on undefined and the labelling step fails; the workflow always sets it.
CI_JOB_NUMBER1.github/workflows/size-limit.yml:10Set for the third-party size-limit action; no repository code reads it.Depends on the action; the workflow always sets it.

CI secrets

Eight secrets, all referenced as secrets.* in GitHub Actions workflows and nowhere else. None appears in the application bundle.

SecretUsed inWhat forWhen absent
NPM_TOKEN.github/workflows/autorelease-excalidraw.yml:23Publishes the @excalidraw packages to npm with tag next on a push to release.The publish step fails; no package is released.
SENTRY_AUTH_TOKEN.github/workflows/sentry-production.yml:35Authenticates sentry-cli to create the production release and upload sourcemaps.sentry-cli fails and no Sentry release is created; the app deploy is unaffected.
SENTRY_ORG.github/workflows/sentry-production.yml:36Sentry organisation for the release.As above.
SENTRY_PROJECT.github/workflows/sentry-production.yml:37Sentry project for the release.As above.
DOCKER_USERNAME.github/workflows/publish-docker.yml:18Docker Hub login for pushing excalidraw/excalidraw:latest.Login fails; no image is pushed.
DOCKER_PASSWORD.github/workflows/publish-docker.yml:19Docker Hub password or access token.As above.
PUSH_TRANSLATIONS_COVERAGE_PAT.github/workflows/locales-coverage.yml:15, 47Personal access token that checks out and pushes the translation coverage update.The locales coverage job cannot push.
GITHUB_TOKENsemantic-pr-title.yml:43, 55; cancel.yml:17; test-coverage-pr.yml:26; size-limit.yml:25Token GitHub issues to each run: labels pull requests, cancels superseded runs, posts coverage and size comments.Always present; GitHub supplies it.

Functions named in this section

FunctionWhereWhat it does
parseEnvVariablespackages/excalidraw/env.cjs:4Parses a .env file with dotenv and adds PKG_NAME and PKG_VERSION from the package's package.json. The package build uses the result as the whole of import.meta.env.

Storage, rotation and validation

Storage. Secrets live only in GitHub Actions secrets. Everything in the .env files is meant to be public: the Firebase web config (its apiKey identifies the project and grants nothing; access is governed by the Firestore and Storage rules described in §8 and §11) and the two RSA public keys used to verify Excalidraw+ export tokens. The Sentry DSN is written into excalidraw-app/sentry.ts rather than configured, which is normal for a browser DSN. No server-side secret exists because the repository contains no server.

Rotation. Nothing in the repository describes rotating any of the eight secrets, and none has an expiry the workflows check. Rotating the Excalidraw+ public key means editing the committed .env file and rebuilding.

Validation. Nothing validates a value at start-up. A malformed VITE_APP_FIREBASE_CONFIG becomes {} with a console warning, and a missing backend URL fails only when a user first shares, collaborates or asks the AI. OSS_STATS_TOKEN in the stats script is the only variable checked before use.

Environment separation. Development and production differ in the share-link backend (json-dev versus json), the Firebase project (excalidraw-oss-dev versus excalidraw-room-persistence), the collaboration and AI servers (localhost versus oss-collab and oss-ai) and the Excalidraw+ origin and key. Staging and Vercel previews are built with .env.production and are distinguished only at run time, by Sentry's hostname check. Because the values are inlined, separation is per build, not per deployment.

Configuration and secrets rating

Configuration and secrets: 6/10, Fair

Fair. Configuration is externalised into committed .env.development and .env.production files with typed declarations in vite-env.d.ts, the two environments are separated, and secrets live only in GitHub Actions secrets. But values are inlined at build time so the Docker image is locked to production endpoints, nothing validates a value at start-up, there is no .env.example or configuration reference, and tracking is false in .env.production but forced true by the build:app script. No rotation is described for any secret. The technical assessment gives the reasoning per criterion.

10. Infrastructure and deployment topology

The repository deploys nothing that runs on a server of its own. What it ships is a static bundle (the excalidraw-app build) and seven npm packages. The bundle reaches users three ways: excalidraw.com and its staging and preview hosts on Vercel, a Docker image that serves the same files from nginx, and, for the library alone, npm. Every server the running app talks to (the collaboration server, the share-link JSON backend, the Firebase project excalidraw-room-persistence, the AI backend, the library backend, Sentry and Simple Analytics) is outside this repository and appears here only as a URL in .env.production or in code. The figure therefore draws those services as opaque boxes.

source and CI deploy targets runtime GitHub repository master and release branches GitHub Actions release-branch workflows Vercel excalidraw.com, staging, vercel.app previews; deployed by Vercel's Git integration Docker Hub excalidraw/excalidraw:latest Self-hosted container nginx serving the build on port 80 npm registry @excalidraw/* tag next User's browser editor bundle (PWA) service worker caches localStorage, IndexedDB external, not in this repo Collaboration server oss-collab.excalidraw.com Share-link JSON backend json.excalidraw.com Firebase (Firestore, Storage) excalidraw-room-persistence AI backend oss-ai.excalidraw.com Library backend cloudfunctions.net/libraries Sentry sentry.io Simple Analytics simpleanalyticscdn.com
Figure 10.1 · deployment topologySolid arrows are defined in this repository; the dashed arrow from the repository to Vercel is Vercel's own Git integration, configured outside it. The release-branch workflows also create a Sentry release (not drawn, to keep the external column readable). The services on the right are drawn as boxes only, because their internals are not in this repository. npm consumers embed the library in their own applications, which choose their own backends.

Environments

Seven environments can be read from the repository. The Sentry environment map in excalidraw-app/sentry.ts is the only place that names staging and preview hosts; there is no .env.staging, so a Vite production build for any Vercel host reads .env.production and talks to the production backends.

EnvironmentWhere it runsConfigurationBackends it usesHow a deploy reaches it
Productionexcalidraw.com on Vercel (vercel.json: output excalidraw-app/build, CORS and caching headers, redirects for /webex and vscode.excalidraw.com).env.production through the build:app script, which sets VITE_APP_GIT_SHA from VERCEL_GIT_COMMIT_SHA and VITE_APP_ENABLE_TRACKING=trueoss-collab.excalidraw.com, json.excalidraw.com, Firebase project excalidraw-room-persistence, oss-ai.excalidraw.com, the library backend, Sentry environment "production", Simple AnalyticsVercel's Git integration, not defined in this repository (the root vercel.json has no git block). A push to release separately marks a Sentry production release.
Staging and previewstaging.excalidraw.com and any *.vercel.app hostNo file of its own: a production build reads .env.production; Sentry maps both hosts to environment "staging"The same production backends as excalidraw.comVercel's Git integration, outside the repository
Developmentlocalhost:3001 (VITE_APP_PORT), started with yarn start.env.development, plus an uncommitted .env.local for personal flagsCollaboration server on localhost:3002, AI backend on localhost:3016, json-dev.excalidraw.com, Firebase project excalidraw-oss-dev; the library site and library backend are the production onesNone; runs on the developer's machine
TestVitest with jsdom, locally and in CI.env.test (VITE_DEBUG_DOM=false)None requiredtest.yml on push to master, test-coverage-pr.yml on pull requests
Self-hosted DockerAny Docker host: nginx:stable-alpine-slim serving excalidraw-app/build on port 80 (docker-compose.yml maps 3000:80)build:app:docker, which sets VITE_APP_DISABLE_SENTRY=true; .env.production is inlined at build timeThe same production backends as excalidraw.com, fixed in the imagepublish-docker.yml pushes excalidraw/excalidraw:latest for linux/amd64, linux/arm64 and linux/arm/v7 on push to release; or a local docker build
npm packagesThe npm registry, consumed by applications that embed the editorPackage builds by scripts/buildPackage.js and scripts/buildBase.js; no app .env appliesWhatever the embedding application wires upautorelease-excalidraw.yml runs yarn release --tag=next on push to release; a stable latest release is run by hand with scripts/release.js --tag=latest
Developer docs sitedev-docs (Docusaurus) on Verceldev-docs/vercel.json: deploys from master only, and every path redirects permanently to plus.excalidraw.com/docsNoneVercel's Git integration, limited to master by deploymentEnabled

What is shared and what is isolated

Shared: the production Firebase project, collaboration server, JSON backend and AI backend are used by excalidraw.com, by staging and preview builds, and by every Docker image built from .env.production, because Vite inlines every VITE_* value at build time (Vite's loadEnv call reads the root .env files at excalidraw-app/vite.config.mts:140). A self-hoster who does not rebuild with their own values writes rooms and share links into the same Firestore collection and JSON backend as excalidraw.com. The library site (libraries.excalidraw.com) and the library backend are the same URLs in development and production.

Isolated: development uses its own Firebase project (excalidraw-oss-dev), its own share-link backend (json-dev.excalidraw.com) and local collaboration and AI servers. The Docker build turns Sentry off, so self-hosted errors never reach excalidraw.com's Sentry project. CI secrets are scoped to the workflows that need them, and OSS_STATS_TOKEN sits in a GitHub environment (stats) that only master can use.

How a deploy reaches each

Four workflows run on a push to the release branch; nothing in the repository deploys excalidraw.com itself.

WorkflowTriggerWhat it deploys
autorelease-excalidraw.ymlpush to releasePublishes the @excalidraw packages to npm with tag next and a hash-suffixed version, using NPM_TOKEN.
build-docker.ymlpush to releaseBuilds the image locally (docker build -t excalidraw .) as a check; pushes nothing.
publish-docker.ymlpush to releaseBuilds with Buildx and QEMU for three platforms and pushes excalidraw/excalidraw:latest to Docker Hub, using DOCKER_USERNAME and DOCKER_PASSWORD. No versioned tag is pushed.
sentry-production.ymlpush to releaseBuilds the app, installs sentry-cli by piping https://sentry.io/get-cli/ to bash, creates and finalises a Sentry release and marks a production deploy. Its sourcemap upload path (./build/static/js/) is not a path the Vite build produces.

The Dockerfile is a two-stage build: node:24 (pinned by digest) runs yarn --frozen-lockfile and yarn build:app:docker, and nginx:stable-alpine-slim (pinned by digest) serves the result. It declares HEALTHCHECK wget -q -O /dev/null http://localhost; docker-compose.yml disables that health check, sets restart: on-failure, and mounts the source tree into a path the nginx stage does not read. .dockerignore excludes everything except the two committed .env files, the app, the packages, public/ and the root config.

Infrastructure and packaging files

The probe's table, reproduced in full with both present and absent rows. Together the rows say the deployment is a static build: there is no infrastructure-as-code (no Terraform, CDK, SAM, Serverless or Kubernetes), no process manifest, and no CI other than GitHub Actions.

Infrastructure and packaging files probed 26 rows
PathPresentWhat it means here
DockerfileyesTwo-stage build, Node to nginx, both base images pinned by digest; the self-hosted deployment.
docker-compose.ymlyesLocal run of the image on port 3000 with the health check disabled.
compose.ymlnoOnly the older file name is used.
serverless.ymlnoNo serverless functions are deployed from here.
template.ymlnoNo AWS SAM or CloudFormation.
template.yamlnoNo AWS SAM or CloudFormation.
samconfig.tomlnoNo AWS SAM.
main.tfnoNo Terraform; the external backends are provisioned elsewhere.
terraformnoNo Terraform directory.
cdk.jsonnoNo AWS CDK.
ProcfilenoNo process to run; the app is static files.
MakefilenoBuilds run through Yarn scripts instead.
k8snoNo Kubernetes manifests.
.github/workflowsyesTwelve GitHub Actions workflows: checks on pull requests and master, and the four release-branch deploy workflows above.
.gitlab-ci.ymlnoGitHub Actions is the only CI.
JenkinsfilenoGitHub Actions is the only CI.
azure-pipelines.ymlnoGitHub Actions is the only CI.
.env.examplenoNo configuration sample; the committed .env.development and .env.production serve as the reference (§9).
.env.samplenoAs above.
composer.jsonnoNo PHP.
package.jsonyesYarn workspaces root (excalidraw-app, packages/*, examples/*) with the build, test and release scripts.
pyproject.tomlnoNo Python.
go.modnoNo Go.
Cargo.tomlnoNo Rust.
pom.xmlnoNo Java.
.gitattributesyesNormalises line endings to LF (* text=auto eol=lf); no deployment role.

Two further files the probe does not look for carry deployment settings: vercel.json (headers, redirects and the output directory of excalidraw.com, with no Content-Security-Policy) and dev-docs/vercel.json (the docs site's redirects). The Firebase project's rules and index files live in firebase-project/, but no workflow deploys them, so what is live in the Firebase console cannot be confirmed from here.

11. Data and persistence

Excalidraw has no database of its own. A drawing lives first in the user's browser, and only a scene that is shared (by link or in a collaboration room) is copied to a server, always encrypted in the browser before it leaves. Every store below is reached from browser code; none is written by a server process in this repository.

evidence correction, sanctioned by the plan

The evidence file reported "none found" for stores: its probe looks for server-side database clients and missed browser storage and the Firebase SDK. The source has eight stores, listed below. Section 11's row count is therefore taken from the source, not from the evidence contract of 0.

Stores

StoreWhat it holdsWho writesEncryptionLifetime
Firestore scenes collectionOne document per collaboration room in collection scenes, keyed by roomId, with fields sceneVersion, iv and ciphertext.saveToFirebase, inside a Firestore transaction, throttled to every 20,000 ms (SYNC_FULL_SCENE_INTERVAL_MS) and on an attempt to leave the page with unsaved changes.AES-GCM with the room key, which travels only in the #room= fragment.No expiry or deletion is set in this repository.
Firebase Storage files bucketImage files of rooms (files/rooms/{roomId}/{fileId}) and of share links (files/shareLinks/{id}/{fileId}).saveFilesToFirebase; read back by loadFilesFromFirebase with a plain fetch to firebasestorage.googleapis.com.Compressed and encrypted with the room or link key before upload.Uploaded with Cache-Control: public, max-age=31536000 (FILE_CACHE_MAX_AGE_SEC); no deletion is set in this repository.
Share-link JSON backendOne compressed, encrypted scene per share link, at VITE_APP_BACKEND_V2_GET_URL (json.excalidraw.com/api/v2/ in production).exportToBackend POSTs it; importFromBackend GETs it by id.Encrypted in the browser; the key travels only in the #json= fragment.Not described: the service is not in this repository.
Browser localStorageThe current scene's elements and app state, the collaborator's name, theme, debug and feature flags, UI preferences, tab-sync version stamps and two editor drafts.LocalData (debounced 300 ms, SAVE_TO_LOCAL_STORAGE_TIMEOUT) and small helpers in the app and editor packages.None; plain JSON in the browser profile.Until the user clears site data. The legacy library key is removed after migration; the publish-library draft is deleted after a successful publish.
IndexedDB files-dbImage files (data URL, MIME type, created and lastRetrieved times) for the local scene.LocalData through its file manager.None.Files not loaded on the canvas for more than 24 hours, and not in the current scene, are deleted by clearObsoleteFiles on a fresh load.
IndexedDB excalidraw-library-dbThe user's shape library.LibraryIndexedDBAdapter, called by the editor's useHandleLibrary.None.Until the user clears site data.
IndexedDB excalidraw-ttd-chats-dbText-to-diagram chat history.TTDIndexedDBAdapter, handed to the editor's TTD dialog as its persistence adapter.None.Until the user clears site data.
Service worker cachesThe precached app shell, fonts, locales, code chunks, lazy chunks, and a file handed over by the operating system's share sheet.The Workbox worker generated by the VitePWA plugin in excalidraw-app/vite.config.mts; cacheMermaidChunks warms the lazy-chunks cache.None; public assets.Workbox expiration per cache (below); the precache is replaced when a new build activates (registerType: "autoUpdate").

Keys, indexes and access patterns

Every store is key-value and every read is by key. No store has a secondary index: firebase-project/firestore.indexes.json declares "indexes": [] and "fieldOverrides": [], Storage, localStorage and the service worker caches have no index concept, and each IndexedDB object store is read by primary key only (one store, files-db, is also scanned whole). Listing Firestore documents is denied by the rules, so no query could need one.

Keys and indexes by store 28 rows
StoreKey or indexAccess pattern it serves
Firestore scenes collectionscenes/{roomId}Get by room id when a user joins and no peer supplies the scene (loadFromFirebase); transactional read, reconcile and write on save (saveToFirebase).
Firestore scenes collectionindexes: noneNo composite or single-field overrides are declared; the only access is by document id, and allow list: if false rules out queries.
Firebase Storage files bucketfiles/rooms/{roomId}/{fileId}Upload once per new image in a room; fetch by id with ?alt=media when a peer or a later visitor needs the image.
Firebase Storage files bucketfiles/shareLinks/{id}/{fileId}Upload the link's images once when the link is created; fetch by id when the link is opened.
Share-link JSON backendshare-link idPOST returns the id, which becomes #json=<id>,<key>; GET {BACKEND_V2_GET}{id} returns the encrypted payload.
Browser localStorageexcalidrawThe scene's non-deleted elements as JSON; written on every debounced save, read at load and when another tab has saved newer data.
Browser localStorageexcalidraw-stateThe app state with non-persisted fields removed; written and read with the elements.
Browser localStorageexcalidraw-collab{ username }; written when the user sets a name, read when joining a room.
Browser localStorageexcalidraw-theme"light", "dark" or "system"; read at start-up, written on every theme change.
Browser localStorageexcalidraw-debug{ enabled } for the debug canvas; read at start-up, written on toggle.
Browser localStorageversion-dataStateTimestamp of the last scene save; another tab compares it on focus or visibility change to decide whether to reload the scene.
Browser localStorageversion-filesTimestamp of the last image save; the same tab-sync check for files.
Browser localStorageexcalidraw-library (legacy)Old library location; read once by LibraryLocalStorageMigrationAdapter, copied to IndexedDB, then removed.
Browser localStorageexcalidraw-feature-flagsFeature flag overrides (COMPLEX_BINDINGS); read once by getFeatureFlag and held in memory.
Browser localStorageexcalidraw.desktopUIMode"compact" or "full"; read at start-up, written when the user changes it.
Browser localStoragemermaid-to-excalidrawThe last Mermaid source typed in the text-to-diagram dialog, restored when it reopens.
Browser localStoragepublish-library-dataThe publish-library form draft (author name, GitHub and Twitter handles, website, library name and description); deleted after a successful publish.
Browser localStorageexcalidraw-minimap-announcement-dismissedWhether the minimap announcement dot was dismissed.
Browser localStorageexcalidraw-oai-api-keyDeclared in EDITOR_LS_KEYS and never read or written (listed in §17).
IndexedDB files-dbfiles-store, key fileIdBatch get by the ids in the scene at load; one set per added file on save; a full scan of entries in clearObsoleteFiles.
IndexedDB excalidraw-library-dbexcalidraw-library-store, key libraryDataLoad and save the whole library as one value.
IndexedDB excalidraw-ttd-chats-dbexcalidraw-ttd-chats-store, key ttdChatsLoad and save the whole chat list as one value.
Service worker cachesprecache (Workbox)The app shell, served offline. Excludes fonts.css, locales, *.chunk-*.js, CodeMirrorEditor, the Firebase SDK chunk and the Mermaid chunks; no file over 2.3 MB (maximumFileSizeToCacheInBytes).
Service worker cachesfonts.woff2 files CacheFirst, 1,000 entries for 90 days; fonts.css StaleWhileRevalidate, 50 entries.
Service worker cacheslocalesLocale bundles CacheFirst, 50 entries for 30 days.
Service worker cacheschunkNamed chunks and CodeMirrorEditor CacheFirst, 50 entries for 90 days.
Service worker cacheslazy-chunksLazy /assets/*.js CacheFirst, 200 entries for 90 days; filled with every Mermaid chunk once the text-to-diagram dialog opens.
Service worker cachesweb-share-target, key shared-fileA file shared to the installed app; read and deleted by restoreFileFromShare. No code in this repository writes it: the generated Workbox worker has no handler for POST /web-share-target.

Files that touch a store

Sixteen files read or write a store. Twelve are in excalidraw-app, seven of them under excalidraw-app/data; four are in the editor packages, which the published library carries into every embedding application.

Files that touch a store 16 rows
FileStoreFunctions that touch itWhat it does
excalidraw-app/data/firebase.tsFirestore, StoragesaveToFirebase, loadFromFirebase, saveFilesToFirebase, loadFilesFromFirebase, uploadBytesToFirebase, createFirebaseSceneDocument, encryptElements, decryptElements, isSavedToFirebaseAll Firebase access: lazy-loads the SDK, encrypts and decrypts room scenes, and uploads and downloads images. The only file that imports the Firebase SDK.
excalidraw-app/data/index.tsJSON backend, StorageexportToBackend, importFromBackend, legacy_decodeFromBackend, isSyncableElementCreates and opens share links, and decides which elements are synced at all. It uploads a link's images through saveFilesToFirebase.
excalidraw-app/data/LocalData.tslocalStorage, files-db, excalidraw-library-dbLocalData, saveDataStateToLocalStorage, isQuotaExceededError, clearObsoleteFiles, LibraryIndexedDBAdapter, LibraryLocalStorageMigrationAdapterThe local persistence layer: debounced scene saves, image storage and clean-up, and the library adapters. It can pause saving while a collaboration session runs or the tab is hidden.
excalidraw-app/data/localStorage.tslocalStoragesaveUsernameToLocalStorage, importUsernameFromLocalStorage, importFromLocalStorage, getElementsStorageSize, getTotalStorageSizeReads the saved scene and the collaborator's name, and measures how much localStorage the app uses.
excalidraw-app/data/tabSync.tslocalStorageisBrowserStorageStateNewer, updateBrowserStateVersion, resetBrowserStateVersionsKeeps two tabs of the app consistent through the version-dataState and version-files timestamps.
excalidraw-app/data/TTDStorage.tsexcalidraw-ttd-chats-dbTTDIndexedDBAdapterLoads and saves the text-to-diagram chat list in IndexedDB.
excalidraw-app/data/cacheMermaidChunks.tslazy-chunks cachecacheMermaidChunksFetches every Mermaid chunk once so the service worker caches them for offline use.
excalidraw-app/useHandleAppTheme.tslocalStorageuseHandleAppThemeReads and writes the excalidraw-theme key and follows the system colour scheme.
excalidraw-app/ExcalidrawPlusIframeExport.tsxlocalStorage (read)handleMessage, parseSceneDataReads the saved scene from localStorage and posts it to Excalidraw+ after the JWT check.
excalidraw-app/components/DebugCanvas.tsxlocalStoragesaveDebugState, loadSavedDebugStatePersists whether the debug canvas is on.
excalidraw-app/components/TopErrorBoundary.tsxlocalStorage (read, clear)componentDidCatch, errorSplashOn a crash, copies all of localStorage into the error splash for the user to paste into a bug report, and offers a button that clears it.
excalidraw-app/vite.config.mtsService worker cacheslazyChunksPluginDeclares the Workbox precache, runtime caches and their expiration, and emits the Mermaid chunk list.
packages/excalidraw/data/EditorLocalStorage.tslocalStorageEditorLocalStorageThe editor package's wrapper for its own keys (EDITOR_LS_KEYS), catching and logging storage errors.
packages/common/src/utils.tslocalStoragegetFeatureFlag, setFeatureFlagReads and writes the excalidraw-feature-flags key.
packages/common/src/editorInterface.tslocalStorageloadDesktopUIModePreference, persistDesktopUIModeReads and writes the excalidraw.desktopUIMode key, ignoring storage errors.
packages/excalidraw/components/App.tsxweb-share-target cacherestoreFileFromShareOpens a file handed over through the web share target and deletes it from the cache.
Functions named in this section 47 rows
FunctionWhereWhat it does
saveToFirebaseexcalidraw-app/data/firebase.ts:190In a Firestore transaction, reads the room document, decrypts and reconciles it with the local elements, and writes the re-encrypted result. Skips the write when the scene version is already saved.
loadFromFirebaseexcalidraw-app/data/firebase.ts:252Gets a room's document by id and returns its decrypted, restored elements, or null when the room has no document.
saveFilesToFirebaseexcalidraw-app/data/firebase.ts:144Uploads encrypted image files under a prefix with a cache max-age of 31,536,000 s, and returns which saved and which failed.
loadFilesFromFirebaseexcalidraw-app/data/firebase.ts:277Fetches image files by id from the Storage REST URL, then decompresses and decrypts each one.
uploadBytesToFirebaseexcalidraw-app/data/firebase.ts:77Uploads raw bytes to a Storage path with optional metadata.
createFirebaseSceneDocumentexcalidraw-app/data/firebase.ts:176Builds the stored room document: the scene version, the ciphertext and the IV.
encryptElementsexcalidraw-app/data/firebase.ts:92Serialises elements to JSON and encrypts them with the room key.
decryptElementsexcalidraw-app/data/firebase.ts:103Decrypts a stored room document back into elements.
isSavedToFirebaseexcalidraw-app/data/firebase.ts:130Compares the scene version with the last version saved for this socket, held in an in-memory cache.
exportToBackendexcalidraw-app/data/index.ts:248Compresses and encrypts the scene with a fresh key, POSTs it to the JSON backend, uploads its images, and returns a URL with #json=id,key.
importFromBackendexcalidraw-app/data/index.ts:202Fetches a share link's payload by id and decrypts it, falling back to the legacy format if the new one fails.
legacy_decodeFromBackendexcalidraw-app/data/index.ts:170Decodes share links in the old format: IV-prefixed ciphertext, and before that a fixed all-zero IV.
isSyncableElementexcalidraw-app/data/index.ts:46Decides whether an element is synced and saved remotely; deleted elements older than one day (DELETED_ELEMENT_TIMEOUT) are not.
LocalDataexcalidraw-app/data/LocalData.ts:124Static class behind local saving: a debounced save of scene and files, flush, and pause and resume locks used while collaborating.
saveDataStateToLocalStorageexcalidraw-app/data/LocalData.ts:73Writes elements and app state to localStorage and bumps the tab-sync version. On a quota error it raises the quota-exceeded flag the app shows as a banner.
isQuotaExceededErrorexcalidraw-app/data/LocalData.ts:111Recognises the browser-specific names and codes of a storage quota error.
clearObsoleteFilesexcalidraw-app/data/LocalData.ts:54Deletes images from files-db that are not in the current scene and were not loaded in the last 24 hours.
LibraryIndexedDBAdapterexcalidraw-app/data/LocalData.ts:236Loads and saves the whole shape library under one key in excalidraw-library-db.
LibraryLocalStorageMigrationAdapterexcalidraw-app/data/LocalData.ts:267Reads the legacy library from localStorage for migration to IndexedDB, and clears it afterwards.
saveUsernameToLocalStorageexcalidraw-app/data/localStorage.ts:11Stores the collaborator's display name.
importUsernameFromLocalStorageexcalidraw-app/data/localStorage.ts:23Reads the collaborator's display name, or null.
importFromLocalStorageexcalidraw-app/data/localStorage.ts:37Reads and parses the saved elements and app state, falling back to empty values on any parse error.
getElementsStorageSizeexcalidraw-app/data/localStorage.ts:76Returns the length of the stored elements string.
getTotalStorageSizeexcalidraw-app/data/localStorage.ts:87Returns the combined length of the elements, app state and collaboration keys.
isBrowserStorageStateNewerexcalidraw-app/data/tabSync.ts:12Reports whether another tab has saved data newer than this tab's copy.
updateBrowserStateVersionexcalidraw-app/data/tabSync.ts:17Stamps a version key with the current time after a save.
resetBrowserStateVersionsexcalidraw-app/data/tabSync.ts:27Sets both version keys back to -1.
TTDIndexedDBAdapterexcalidraw-app/data/TTDStorage.ts:11Loads and saves the text-to-diagram chat list in excalidraw-ttd-chats-db, returning an empty list when loading fails.
cacheMermaidChunksexcalidraw-app/data/cacheMermaidChunks.ts:21Five seconds after the dialog opens, fetches the list of Mermaid chunks and each chunk so the service worker caches them.
useHandleAppThemeexcalidraw-app/useHandleAppTheme.ts:11React hook that keeps the chosen theme in localStorage and follows the system scheme when "system" is chosen.
handleMessageexcalidraw-app/ExcalidrawPlusIframeExport.tsx:157Handles postMessage requests from the Excalidraw+ origin: verifies the JWT, then posts the localStorage scene back or an error.
parseSceneDataexcalidraw-app/ExcalidrawPlusIframeExport.tsx:42Parses the raw localStorage elements and app state and prepares the scene and its images for export.
saveDebugStateexcalidraw-app/components/DebugCanvas.tsx:397Stores whether the debug canvas is enabled.
loadSavedDebugStateexcalidraw-app/components/DebugCanvas.tsx:419Reads the stored debug canvas setting.
componentDidCatchexcalidraw-app/components/TopErrorBoundary.tsx:26Reports a render crash to Sentry and copies localStorage into component state for the error splash.
errorSplashexcalidraw-app/components/TopErrorBoundary.tsx:75Renders the crash screen with a bug-report link, the localStorage dump and a button that clears localStorage and reloads.
lazyChunksPluginexcalidraw-app/vite.config.mts:26Vite plugin that keeps large lazy dependencies out of the precache and emits the Mermaid chunk list for runtime caching.
EditorLocalStoragepackages/excalidraw/data/EditorLocalStorage.ts:5Static has, get, set and delete over the editor's localStorage keys, logging a warning instead of throwing.
getFeatureFlagpackages/common/src/utils.ts:1222Returns a feature flag, reading the stored overrides once and caching them in memory.
setFeatureFlagpackages/common/src/utils.ts:1238Sets a feature flag in memory and writes all flags to localStorage.
loadDesktopUIModePreferencepackages/common/src/editorInterface.ts:194Reads the saved compact or full desktop UI mode, or null.
persistDesktopUIModepackages/common/src/editorInterface.ts:211Writes the desktop UI mode, ignoring storage errors.
restoreFileFromSharepackages/excalidraw/components/App.tsx:4920Takes the shared file from the web-share-target cache, loads it onto the canvas and deletes it from the cache.
useHandleLibrarypackages/excalidraw/data/library.ts:677Editor hook that loads and saves the library through the adapter the host app passes, runs the one-time migration, and handles #addLibrary links.
restoreElementspackages/excalidraw/data/restore.ts:960Upgrades elements of any older shape to the current schema, filling missing fields with defaults.
reconcileElementspackages/excalidraw/data/reconcile.ts:73Merges local and remote element lists, keeping the higher version of each element and the local copy of one being edited. Equal versions are settled by the lower versionNonce, so every client reaches the same result.
clearAppStateForLocalStoragepackages/excalidraw/appState.ts:325Strips the app state down to the fields marked for browser storage before it is saved or after it is read.

Personal data held

Personal data held: the collaborator's username (localStorage excalidraw-collab, broadcast encrypted to the room), the library publisher's name, GitHub and Twitter handles and website (localStorage publish-library-data, posted to the library backend), and the drawings and images themselves. The AI features post the frame image and its text to VITE_APP_AI_BACKEND without end-to-end encryption.

No account, email address or password is stored anywhere: users do not sign in. The app reads, but never writes, the excplus-auth cookie set by Excalidraw+, using only its presence to switch the sign-in and sign-up links, the footer and the welcome screen. On a crash, componentDidCatch places the whole of localStorage (including the scene and username) in the error splash for the user to copy; it is not sent to Sentry, which receives the error and React's component stack.

Layers and tiers

Layers. The app's data access is separated from its UI: it sits in excalidraw-app/data, behind LocalData, the FileManager class it builds on, and the library and TTD persistence adapters. The editor package never calls these directly; the app hands them in through props and hooks (useHandleLibrary takes LibraryIndexedDBAdapter, the TTD dialog takes TTDIndexedDBAdapter, and the app's change handler calls LocalData), so an embedding application supplies its own persistence. The separation is not complete: four app files outside excalidraw-app/data (theme, debug canvas, error boundary, Excalidraw+ export) and three places in the editor packages (feature flags, desktop UI mode, the share-target cache) read or write browser storage directly, and the editor's own keys go through the thin EditorLocalStorage wrapper. There is no ORM or repository abstraction over Firestore; firebase.ts is the single module that talks to it.

TierStoresRole
Primary, browser-localBrowser localStorage, IndexedDB files-db, IndexedDB excalidraw-library-db, IndexedDB excalidraw-ttd-chats-dbThe working copy of every drawing, and the only copy of a drawing that has never been shared.
Shared copyFirestore scenes collection, Firebase Storage files bucket, Share-link JSON backendEncrypted copies of rooms and share links, so a joiner or a link recipient can load a scene when no peer is present.
CacheService worker caches; an in-memory map of the last saved scene version per socketOffline start-up and asset delivery; skipping Firestore writes when nothing changed.
Archive or cold storageNoneNo archive tier exists in this repository.
Search or analytics copyNoneNo store is indexed for search or copied for analytics; Simple Analytics receives event names, not scene data.

Integrity, schema evolution and retention

Integrity. The Firestore write is a transaction that decrypts the stored scene, reconciles it with the local elements by element version through reconcileElements, and writes the result, so two clients saving at once do not overwrite each other's elements. Nothing else is transactional: IndexedDB and localStorage writes are independent, and Storage uploads are one object per file. The Firestore and Storage rules allow get and write to anyone and deny list on Firestore, so integrity against a hostile writer rests on the room id being unguessable (10 random bytes); see §8.

Schema evolution. There are no migrations in the database sense. Every element read from any store passes through restoreElements, which upgrades old shapes; share links in the old format are read by legacy_decodeFromBackend; and the library moved from localStorage to IndexedDB through LibraryLocalStorageMigrationAdapter, run once by useHandleLibrary. The Firestore document carries sceneVersion, which is a content version used for reconciliation, not a schema version.

Retention. No retention is set in this repository for Firestore, Storage or the JSON backend: rooms, share links and their images stay until someone outside the repository removes them. In the browser, cached images expire after 24 hours unused, deleted elements older than one day are left out of what is synced, and the service worker caches expire by the limits above.

Data and persistence rating

Data and persistence: 7/10, Good

Good. Data access has its own layer in excalidraw-app/data, which the editor reaches through props; the Firestore write is a transaction that reconciles by element version, everything leaving the browser is encrypted, and schema evolution is handled in restoreElements, legacy share-link decoding and a localStorage-to-IndexedDB migration. The gaps: no retention or deletion for rooms, share links or files on the server side, a local user's only copy living in one browser profile, open Firestore rules that let anyone holding a room id overwrite it, and personal data with no stated retention. The technical assessment gives the reasoning per criterion.

12. External integrations

As §1 sets out, the repository contains no server code: the collaboration server, the share-link JSON backend, the AI backend and the library backend are external services reached by URLs set in .env.production, and each has a row below. Every integration is therefore a call from the browser (or from CI) to something this repository does not deploy, and each is optional to the core job: a user can draw, save to the browser and export a file with every external service down. What fails is the feature that needs the service, and the application code never retries it with backoff; §13 lists what the user sees in each case, from an alert or an error state to nothing at all.

The inventory has one row for each of the 85 hosts the evidence probe found, with its kind, followed by 10 runtime services the probe missed because they are named only in .env files, in excalidraw-app/index.html, in workflows, or through an SDK rather than a URL. Most of the 85 are not integrations at all: links in the UI or documentation, test fixtures, licence and attribution URLs in font metadata, XML namespaces and references in comments. They stay in the table so a reader can see that each was looked at. The kinds used are: runtime service (the shipped app or CI calls it), embed provider (the editor rewrites a pasted link into an iframe or loads a widget script for it), UI link (an anchor the user may click), redirect (a Vercel rewrite), doc link, test fixture, metadata (a URL inside a font's licence text) and comment.

External integrations and named hosts 95 rows
HostKindWhere namedWhat it is forWhen it is down
api.example.comtest fixturepackages/excalidraw/components/TTDDialog/utils/TTDstreamFetch.test.ts:66Placeholder AI endpoint for the streaming fetch tests; requests are mocked.Nothing; never contacted.
backend.excalidraw.comruntime service (CI)scripts/stats/post.mjs:30Default stats backend that stats.yml posts bundle size and perf benchmarks to on push to master.The stats job fails; the product and other CI are unaffected.
bugs.webkit.orgcommentpackages/excalidraw/clipboard.ts:562Reference to a Safari bug a workaround exists for.Nothing.
caniuse.comcommentpackages/element/src/textWrapping.ts:134Browser support reference for a regex feature.Nothing.
cdn.domain.comdoc linkpackages/excalidraw/CHANGELOG.md:446Example value for EXCALIDRAW_ASSET_PATH in the changelog.Nothing; a placeholder.
chinese-font.netlify.appcommentpackages/excalidraw/fonts/Xiaolai/index.ts:1Source of the font subsetting approach.Nothing.
codesandbox.iodoc linkREADME.md:110, packages/excalidraw/README.md:130"Used by" list and an example sandbox.Nothing.
cookbook.openai.comcommentpackages/excalidraw/data/ai/types.ts:68Reference for the AI message types.Nothing.
crowdin.comUI link (generated)scripts/locales-coverage-description.js:193, 202Links to the Crowdin translation project, written into the translation coverage description.Links dead; nothing breaks. Translation sync itself is configured outside this repository.
deepwiki.comdoc linkREADME.md:33"Ask DeepWiki" badge.Badge image missing.
developer.mozilla.orgcomment, doc linkpackages/common/src/constants.ts:139Web API references.Nothing.
devina.iocommentpackages/element/src/textWrapping.ts:193Regex reference.Nothing.
discord.ggUI linkexcalidraw-app/App.tsx:1238, packages/excalidraw/components/main-menu/DefaultItems.tsx:396Community chat link in the menu, command palette and docs.Link dead.
dizajndesign.skmetadatapackages/excalidraw/fonts/Excalifont/index.ts:24Designer URL in the Excalifont licence metadata.Nothing; never fetched.
docs.excalidraw.comUI link, doc sitepackages/excalidraw/components/BraveMeasureTextError.tsx:22, dev-docs/docusaurus.config.js:14Developer docs, now redirected to plus.excalidraw.com/docs by dev-docs/vercel.json; linked from the Brave fingerprinting error.The help link in the Brave error is dead.
docusaurus.iodoc linkdev-docs/README.md:5Docs generator credit.Nothing.
drafts.csswg.orgcommentpackages/common/src/constants.ts:140CSS spec reference.Nothing.
drive.google.comembed providerpackages/element/src/embeddable.ts:271Google Drive preview links become iframes.Drive embeds on the canvas render blank.
easings.netcommentpackages/element/src/shape.ts:1321Trailing comment naming the easing curve.Nothing.
eliot-jones.comcommentpackages/element/src/bounds.ts:547Maths reference.Nothing.
embed.reddit.comembed providerpackages/element/src/embeddable.ts:388widgets.js loaded inside the sandboxed srcdoc iframe that renders a Reddit post.Reddit embeds show a plain link instead of the post.
en.wikipedia.orgcommentpackages/excalidraw/data/blob.ts:485PNG chunk format reference.Nothing.
esm.rundoc linkpackages/excalidraw/README.md:118CDN example for loading the package in a browser.Nothing in this repository.
esm.shruntime servicepackages/excalidraw/fonts/ExcalidrawFontFace.ts:11, dev-docs/src/theme/ReactLiveScope/index.js:15Last-resort font source: every font face appends an esm.sh URL after the self-hosted ones. The dev docs load the package's assets from it.Fonts that fail to load locally fall back to a system font; self-hosted fonts are unaffected.
example.comtest fixturepackages/excalidraw/clipboard.test.ts:99, packages/excalidraw/components/Trans.tsx:62Placeholder links in tests and in a comment explaining Trans.Nothing.
excalidraw.comthe product's own hostpackages/excalidraw/data/library.ts:55, packages/excalidraw/charts/charts.helpers.ts:888Library install allowlist entry, Sentry's production hostname, and a comment link to a share-link scene.The app itself is down; see §14.
excalidraw.com.mxtest fixturepackages/excalidraw/data/library.test.ts:75Look-alike domain the library allowlist must reject.Nothing.
excalidraw.comxtest fixturepackages/excalidraw/data/library.test.ts:69Look-alike domain the library allowlist must reject.Nothing.
excalidraw.nyc3.cdn.digitaloceanspaces.comruntime servicescripts/woff2/woff2-vite-plugins.js:2, README.md:3CDN for the Assistant UI font, whose woff2 URLs the build plugin writes into the app's CSS; also README images.The UI font falls back to a system font; drawing is unaffected.
feathericons.comcommentpackages/excalidraw/components/icons.tsx:983Icon attribution.Nothing.
firebasestorage.googleapis.comruntime serviceexcalidraw-app/data/firebase.ts:288Firebase Storage REST endpoint the app fetches encrypted images from for rooms and share links.Images in shared scenes and rooms are marked as errored; the rest of the scene loads.
first.exampletest fixturepackages/excalidraw/tests/tooltip.test.tsx:222Placeholder link in tooltip tests.Nothing.
fontawesome.comcommentpackages/excalidraw/components/icons.tsx:2Icon licence attribution.Nothing.
fontdrop.infocommentpackages/common/src/font-metadata.ts:12Tool used to read font metrics.Nothing.
for-webex.excalidraw.comredirectvercel.json:54Vercel rewrites /webex/* on excalidraw.com to the Webex integration host.The /webex path fails; the editor is unaffected.
giphy.comembed providerpackages/element/src/embeddable.ts:525Giphy links become an embed URL.Giphy embeds render blank.
gist.github.comembed providerpackages/element/src/embeddable.ts:400Gist script loaded inside a sandboxed srcdoc iframe.Gist embeds render empty.
github.coprobe artefactnone foundA search of the source finds no literal occurrence; the probe most likely cut a github.com URL short.Not applicable.
github.comUI link, doc link, CIexcalidraw-app/App.tsx:1199, excalidraw-app/components/TopErrorBoundary.tsx:69, dev-docs/docusaurus.config.js:39Repository and issue links (the crash screen pre-fills a new issue); CI runs on GitHub Actions and stats.yml fetches from origin.Links dead for users; every workflow stops.
googlecloudcheatsheet.withgoogle.comdoc linkREADME.md:110"Used by" list.Nothing.
img.shields.iodoc linkREADME.md:26README badges.Badges missing.
instagram.comtest fixturepackages/element/tests/embeddable.test.ts:254Bare domain case of the Instagram embed tests (also in the embed allowlist).Nothing.
johnresig.comcommentpackages/element/src/image.ts:112Reference for a technique.Nothing.
learn.microsoft.comcommentpackages/common/src/constants.ts:141Font reference.Nothing.
libraries.excalidraw.comruntime service (UI)packages/excalidraw/components/PublishLibrary.tsx:406, .env.production (VITE_APP_LIBRARY_URL)Public library site the "Browse libraries" button opens; it hands a chosen library back through #addLibrary.Browsing and installing new libraries fails; installed libraries in IndexedDB are unaffected.
library.excalidraw.comtest fixturepackages/excalidraw/data/library.test.ts:14Subdomain case of the library allowlist tests.Nothing.
link.excalidraw.comcommentpackages/element/src/cropElement.ts:208Link to a scene illustrating the crop maths; the host is also in the embed allowlist.Nothing.
localhostlocal.env.development:10, excalidraw-app/tests/firebase.test.ts:9Development collaboration, AI and Excalidraw+ servers, and test set-up.Development features that need those servers fail locally.
marketplace.visualstudio.comredirectvercel.json:64Vercel redirect to the VS Code extension.Redirect target dead.
mathiasbynens.github.iocommentpackages/excalidraw/components/App.tsx:6581Unicode reference.Nothing.
mermaid.js.orgUI linkpackages/excalidraw/components/TTDDialog/MermaidToExcalidraw.tsx:73Link to Mermaid syntax docs in the Mermaid import dialog.Link dead.
nextjs.orgdoc linkexamples/with-nextjs/README.md:1Next.js example README.Nothing.
npmjs.comdoc linkdev-docs/docs/@excalidraw/excalidraw/api/utils/utils-intro.md:7Package page link.Nothing.
observablehq.comcommentpackages/fractional-indexing/src/index.ts:3Source of the fractional indexing algorithm.Nothing.
opencollective.comdoc linkREADME.md:114Sponsorship links and avatars.README images missing.
pele.rundoc linkpackages/excalidraw/CHANGELOG.md:219Layout engine credited in the changelog.Nothing.
platform.openai.comcommentpackages/excalidraw/data/ai/types.ts:76API references for the AI message types.Nothing.
platform.twitter.comembed providerpackages/element/src/embeddable.ts:370widgets.js loaded inside the sandboxed srcdoc that renders a tweet.Tweet embeds show a plain link.
player.vimeo.comembed providerpackages/element/src/embeddable.ts:240, packages/excalidraw/components/App.tsx:1119Vimeo embed URL, and an origin the editor accepts postMessage events from.Vimeo embeds render blank.
plus.excalidraw.comUI link, redirectdev-docs/vercel.json:13, excalidraw-app/components/EncryptedIcon.tsx:11, .env.production (VITE_APP_PLUS_LP)Excalidraw+ marketing site, blog and SDK docs; promotional links in the app.Links and docs redirects dead.
pomax.github.iocommentpackages/math/src/curve.ts:445Bezier maths reference.Nothing.
reddit.comembed providerpackages/element/src/embeddable.ts:382Canonical post URL written into the Reddit embed.Reddit embeds show nothing useful.
scripts.sil.orgmetadatapackages/excalidraw/fonts/Excalifont/index.ts:28SIL Open Font Licence URL in font metadata.Nothing; never fetched.
second.exampletest fixturepackages/excalidraw/tests/tooltip.test.tsx:226Placeholder link in tooltip tests.Nothing.
sentry.ioruntime serviceexcalidraw-app/sentry.ts:22, .github/workflows/sentry-production.yml:25, scripts/stats/perf.mjs:90Error reporting from the production app; sentry-cli download and release in CI; blocked during perf runs.Errors go unreported and the Sentry release job fails; users notice nothing.
stackoverflow.comcommentexcalidraw-app/app_constants.ts:13References in nine files.Nothing.
staging.excalidraw.comruntime service (CI)scripts/stats/perf.mjs:36, excalidraw-app/sentry.ts:7Staging deployment the perf benchmark loads; Sentry's staging environment name.The perf benchmark fails.
twitter.comembed providerpackages/element/src/embeddable.ts:363Canonical tweet URL written into the tweet embed.Tweet embeds show a plain link.
unicode.orgcommentpackages/element/src/textWrapping.ts:191Line breaking reference.Nothing.
unpkg.comdoc linkpackages/utils/README.md:40CDN example in the utils README.Nothing.
vercel.comdoc linkREADME.md:124Sponsor badge.Nothing.
webpack.js.orgdoc linkpackages/excalidraw/CHANGELOG.md:365Bundler configuration reference.Nothing.
www.excalidraw.comtest fixturepackages/common/tests/url.test.tsx:17URL normalisation and allowlist tests.Nothing.
www.figma.comembed providerpackages/element/src/embeddable.ts:292Figma links become a Figma embed URL.Figma embeds render blank.
www.geeksforgeeks.orgcommentpackages/element/src/elbowArrow.ts:1644Algorithm reference for elbow arrow routing.Nothing.
www.instagram.comembed providerpackages/element/src/embeddable.ts:315Instagram post links become an embed URL.Instagram embeds render blank.
www.linkedin.comdoc linkdev-docs/docusaurus.config.js:105Docs site footer link.Nothing.
www.npmjs.comcomment, doc linkpackages/excalidraw/fonts/Excalifont/index.ts:11, README.md:27Font package sources and the npm package page.Nothing.
www.w3.orgXML namespacepackages/common/src/constants.ts:412, packages/element/src/renderElement.ts:350SVG and XLink namespace URIs; identifiers, never fetched.Nothing.
www.youtube.comembed providerpackages/element/src/embeddable.ts:208YouTube links become youtube.com/embed iframes.YouTube embeds render blank.
x-excalidraw.comtest fixturepackages/excalidraw/data/library.test.ts:66Look-alike domain the library allowlist must reject.Nothing.
x.comUI link, embed providerexcalidraw-app/App.tsx:1213, packages/excalidraw/components/main-menu/DefaultItems.tsx:389Social link in the menu; also in the embed allowlist.Link dead.
xexcalidraw.comtest fixturepackages/excalidraw/data/library.test.ts:63Look-alike domain the library allowlist must reject.Nothing.
youtu.betest fixturepackages/element/tests/embeddable.test.ts:11Short-link cases of the YouTube embed tests.Nothing.
youtube.comUI linkexcalidraw-app/App.tsx:1252, packages/excalidraw/components/HelpDialog.tsx:52Channel link in the help dialog and command palette.Link dead.
json.excalidraw.comruntime service (missed by probe).env.production (VITE_APP_BACKEND_V2_*), excalidraw-app/data/index.ts:207, 276Share-link backend: stores the encrypted scene and returns its id.Creating and opening #json= share links fails with an alert; local drawing is unaffected.
oss-collab.excalidraw.comruntime service (missed by probe).env.production (VITE_APP_WS_SERVER_URL), excalidraw-app/collab/Collab.tsx:545Socket.IO relay (excalidraw-room) that carries encrypted scene updates, cursors and idle state between peers.No live collaboration: the room loads its last saved scene from Firestore, but peers do not see each other's changes.
oss-ai.excalidraw.comruntime service (missed by probe).env.production (VITE_APP_AI_BACKEND), excalidraw-app/components/AI.tsx:67, 171AI backend for text-to-diagram and diagram-to-code.The AI dialogs show an error; nothing else changes.
us-central1-excalidraw-room-persistence.cloudfunctions.netruntime service (missed by probe).env.production (VITE_APP_LIBRARY_BACKEND), packages/excalidraw/components/PublishLibrary.tsx:318Cloud Function that receives library submissions.Publishing a library fails with an error.
Firestore (Firebase SDK)runtime service (missed by probe)excalidraw-app/data/firebase.ts:190, 252Collection scenes, one encrypted document per collaboration room, written in a transaction and read when a room opens.Rooms cannot save or load their persisted scene, so a user joining an idle room finds it empty; peers connected through the Socket.IO server still sync live.
scripts.simpleanalyticscdn.comruntime service (missed by probe)excalidraw-app/index.html:224Simple Analytics script, injected async in production builds only; receives the events tracking forwards.No analytics; the script is async, so the app is unaffected.
app.excalidraw.comruntime service (missed by probe).env.production (VITE_APP_PLUS_APP), excalidraw-app/ExcalidrawPlusIframeExport.tsx:16Excalidraw+ app: the only origin the export iframe answers, and the target of export and sign-in links.Export to Excalidraw+ and sign-in fail; the editor is unaffected.
raw.githubusercontent.comruntime service (missed by probe)packages/excalidraw/data/library.ts:57, 733Allowlisted source for installing a library from an excalidraw-libraries pull request.Installing a library from a GitHub link fails.
registry.npmjs.orgruntime service (CI, missed by probe).github/workflows/autorelease-excalidraw.yml:23Package install in every workflow and the Docker build; publishing the @excalidraw packages on release.CI, the Docker build and releases fail.
Docker Hubruntime service (CI, missed by probe).github/workflows/publish-docker.yml, Dockerfile:1, 16Base images node:24 and nginx:stable-alpine-slim (pinned by digest) and the push of excalidraw/excalidraw:latest.The image cannot be built or published; nothing else depends on it.

Outbound calls

Outbound calls: 33 hosts called from code, 8 named only in tests, 1 local, 23 only in comments; 4 lines match a risk pattern and there is 1 install hook (prepare: husky install). The table below has one row per host the evidence lists as called from code. "Called from code" is the probe's term for a URL on a non-comment line; for many of these the code only renders a link or checks an origin, and the "what for" column says which. The probe's own connection count is 17 fetch call sites in 14 files, 3 XMLHttpRequest uses (all in packages/excalidraw/subset/woff2/woff2-bindings.ts, the Emscripten loader for the bundled woff2 WebAssembly, which reads local files), one curl and one git fetch (.github/workflows/stats.yml:57, fetching the previous commit from the repository's own origin). The live fetch targets that matter are the share-link backend, Firebase Storage, the AI backend, the library backend and the library URL; one of them, the scene URL in a #url= link, is any URL the link names, with no allowlist (see §8).

Hosts called from code 33 rows
HostCalled fromWhat forExpected?
github.comexcalidraw-app/App.tsx:1199, excalidraw-app/components/TopErrorBoundary.tsx:69, dev-docs/docusaurus.config.js:39Repository and issue links in the app, the crash screen and the docs; 31 code lines, no request made by the app.Yes: an open-source project linking its repository.
excalidraw.compackages/excalidraw/data/library.ts:55, packages/excalidraw/charts/charts.helpers.ts:888Library URL allowlist entry and a comment-style link; the hostname is the product itself.Yes.
www.youtube.compackages/element/src/embeddable.ts:208Rewrites a YouTube link into an embed iframe URL when a user embeds a video.Yes: embedding is a feature, and only user-supplied links are loaded.
drive.google.compackages/element/src/embeddable.ts:271Rewrites a Drive link into its preview iframe URL.Yes, as above.
plus.excalidraw.comdev-docs/docusaurus.config.js:69, dev-docs/vercel.json:13Docs navigation and redirects to the SDK docs; the app reaches it through VITE_APP_PLUS_LP.Yes: the commercial sibling product.
www.instagram.compackages/element/src/embeddable.ts:315Builds the Instagram post embed URL.Yes.
discord.ggexcalidraw-app/App.tsx:1238, packages/excalidraw/components/BraveMeasureTextError.tsx:36Community chat links.Yes.
player.vimeo.compackages/element/src/embeddable.ts:240, packages/excalidraw/components/App.tsx:1119Vimeo embed URL, and an origin check before acting on a postMessage from a Vimeo iframe.Yes.
docs.excalidraw.comdev-docs/docusaurus.config.js:14, packages/excalidraw/components/BraveMeasureTextError.tsx:22Docs site URL and a help link.Yes.
scripts.sil.orgpackages/excalidraw/fonts/Excalifont/index.ts:28, packages/excalidraw/fonts/Xiaolai/index.ts:232Licence URL inside font metadata strings; never requested.Yes.
x.comexcalidraw-app/App.tsx:1213, packages/excalidraw/components/main-menu/DefaultItems.tsx:389Social link.Yes.
crowdin.comscripts/locales-coverage-description.js:193Links written into the translation coverage text by a CI script.Yes.
dizajndesign.skpackages/excalidraw/fonts/Excalifont/index.ts:24Designer URL inside font metadata; never requested.Yes.
esm.shpackages/excalidraw/fonts/ExcalidrawFontFace.ts:11, dev-docs/src/theme/ReactLiveScope/index.js:15Fallback font URL appended after the self-hosted ones; the docs' asset path.Yes for a library that must find its fonts when the host serves none; it does mean the deployed app can load fonts from a public CDN.
sentry.io.github/workflows/sentry-production.yml:25, scripts/stats/perf.mjs:90Downloads sentry-cli in CI (flagged below); blocks Sentry requests during perf runs. The app's DSN at excalidraw-app/sentry.ts:22 is a third use the probe did not count.Yes for error reporting; the way the CLI is installed is not.
youtube.comexcalidraw-app/App.tsx:1252, packages/excalidraw/components/HelpDialog.tsx:52Channel link.Yes.
backend.excalidraw.comscripts/stats/post.mjs:30Posts bundle and perf stats from CI with OSS_STATS_TOKEN.Yes: the project's own stats service.
easings.netpackages/element/src/shape.ts:1321Reference in a trailing comment the probe read as code.Yes.
embed.reddit.compackages/element/src/embeddable.ts:388Widget script inside the sandboxed Reddit embed.Yes: third-party script, confined to a sandboxed srcdoc iframe.
excalidraw.nyc3.cdn.digitaloceanspaces.comscripts/woff2/woff2-vite-plugins.js:2Font CDN written into the built app's CSS.Yes: the project's own CDN bucket.
firebasestorage.googleapis.comexcalidraw-app/data/firebase.ts:288Fetches encrypted image files for rooms and share links.Yes: the app's file store.
for-webex.excalidraw.comvercel.json:54Vercel rewrite target for /webex.Yes.
giphy.compackages/element/src/embeddable.ts:525Builds the Giphy embed URL.Yes.
gist.github.compackages/element/src/embeddable.ts:400Gist script inside a sandboxed srcdoc iframe.Yes.
libraries.excalidraw.compackages/excalidraw/components/PublishLibrary.tsx:406Link to the public library site in the publish dialog.Yes.
marketplace.visualstudio.comvercel.json:64Redirect to the VS Code extension.Yes.
mermaid.js.orgpackages/excalidraw/components/TTDDialog/MermaidToExcalidraw.tsx:73Syntax docs link.Yes.
platform.twitter.compackages/element/src/embeddable.ts:370Widget script inside the sandboxed tweet embed.Yes, sandboxed as for Reddit.
reddit.compackages/element/src/embeddable.ts:382Canonical post URL in the Reddit embed.Yes.
staging.excalidraw.comscripts/stats/perf.mjs:36Staging app the perf benchmark loads in CI.Yes.
twitter.compackages/element/src/embeddable.ts:363Canonical tweet URL in the embed.Yes.
www.figma.compackages/element/src/embeddable.ts:292Builds the Figma embed URL.Yes.
www.linkedin.comdev-docs/docusaurus.config.js:105Docs footer link.Yes.

Nothing in the list is unexpected for a drawing app with embeds, collaboration and a docs site: every host is the project's own, a Google or Firebase service it uses, an embed provider a user chooses, or a link. The 8 hosts named only in tests and the 23 named only in comments are rowed in the inventory above; the one local host is the development server set.

Install hook and risk-pattern lines, one row each:

LinePatternWhereVerdict
prepare: husky installinstall hookpackage.json:87Benign. It installs the git hooks in .husky on every yarn install; the only hook, pre-commit, has its one command (yarn lint-staged) commented out, so it runs nothing. It makes no network call.
curl -sL https://sentry.io/get-cli/ | bashremote script piped to a shell.github/workflows/sentry-production.yml:25A finding. The release job runs an unpinned, unverified script from sentry.io, and the sentry-cli binary it installs runs in the next step with SENTRY_AUTH_TOKEN, SENTRY_ORG and SENTRY_PROJECT in its environment; whoever controls that URL controls the job and those secrets. Every action in the workflows is pinned to a SHA, which makes this the exception. Carried to the security rating in §8 and the assessment.
<Toast.ProgressBar progress={progress.progress} />paste, tunnel, webhook or file-drop hostpackages/excalidraw/actions/actionExport.tsx:136False positive: the word "toast" in a UI component name matched a host pattern. No network call.
message={appState.toast.message}paste, tunnel, webhook or file-drop hostpackages/excalidraw/components/LayerUI.tsx:693False positive for the same reason: the toast notification's message prop.
"raw.githubusercontent.com/excalidraw/excalidraw-libraries",download at run time from raw source hostingpackages/excalidraw/data/library.ts:57Benign. It is an entry in ALLOWED_LIBRARY_URLS, which narrows where a library may be installed from; the download only happens when a user opens an #addLibrary link and accepts, and the file fetched is library JSON, not code.

Functions named in this section

FunctionWhereWhat it does
fetchbrowser and Node built-inThe standard HTTP request API; every runtime call to an external service in the app goes through it, except the Firebase SDK and Socket.IO.

13. Error handling and resilience

Excalidraw has no central error strategy. It follows one convention: an error is caught close to the call that raised it and turned into state the user can see. That state takes one of five forms. A failed share-link import raises window.alert. Editor failures set appState.errorMessage, which the library shows in its error dialog. A failed collaboration save sets the collaboration error indicator and opens a dialog once per message. A full browser store sets the localStorageQuotaExceededAtom flag, which shows a red banner. A failed image shows an error placeholder on the canvas. Almost every handler also calls console.error. On excalidraw.com, staging and vercel.app, Sentry's captureConsoleIntegration turns each of those calls into an error event (see section 16). A React TopErrorBoundary wraps the whole app (excalidraw-app/App.tsx:1321) and catches any render error that nothing below it caught.

All of this runs in the browser. The repository holds no server code, so dead letters, queues and circuit breakers have nothing to attach to. Resilience here means three things: the tab staying usable, the scene not being lost, and collaboration healing itself after a dropped message.

Failure modes

One row per failure the code handles on purpose. "Where handled" names the function that catches the failure. Each function is described in the table at the end of this section.

FailureWhere handledWhat the user sees
Share-link export fails or is too largeexportToBackend excalidraw-app/data/index.ts:248-307, onExportToBackend excalidraw-app/App.tsx:771-809A backend reply of RequestTooLargeError becomes "couldNotCreateShareableLinkTooBig". Any other failure becomes "couldNotCreateShareableLink". An image over FILE_UPLOAD_MAX_BYTES (4 MiB) makes encodeFilesForUpload throw first. The message is rethrown and shown in the export dialog.
Share-link import failsimportFromBackend excalidraw-app/data/index.ts:202-242A non-OK response or a network error raises window.alert ("importBackendFailed"), and the app opens an empty import. If the payload fails to decode in the current format, the function falls back to legacy_decodeFromBackend before giving up.
Socket connect_errorstartCollaboration excalidraw-app/collab/Collab.tsx:533-557Nothing at first. A one-shot connect_error listener runs fallbackInitializationHandler, which loads the room from Firestore through initializeRoom. If socketIOClient itself throws, the error dialog opens with its message.
No initial scene within 5,000 msstartCollaboration excalidraw-app/collab/Collab.tsx:583-586Nothing visible. After INITIAL_SCENE_UPDATE_TIMEOUT (5,000 ms) the same fallback loads the scene from Firestore. If that load fails, it is logged and the client waits for peers to send the scene (Collab.tsx:760-763).
Firestore save failssaveCollabRoomToFirebase excalidraw-app/collab/Collab.tsx:334-374The collaboration error indicator shows "collabSaveFailed", or "collabSaveFailed_sizeExceeded" when the message matches "is longer than ... bytes". The dialog opens once per distinct message. The next save is retried only by the 20,000 ms throttle (queueSaveToFirebase), not on a backoff.
File upload failssaveFilesToFirebase excalidraw-app/data/firebase.ts:144-174, saveFiles excalidraw-app/data/FileManager.ts:92-136Nothing, per file. Each failed upload is collected in erroredFiles and not retried; FileManager.ts:107 says so in a comment ("if errored during save, won't retry due to this check"). Only a failure to load the Storage SDK fails the whole save, which queueFileUpload turns into appState.errorMessage. Share links ignore erroredFiles.
Image load failsupdateImageCache packages/excalidraw/components/App.tsx:10624-10652, loadFilesFromFirebase excalidraw-app/data/firebase.ts:277-320The image element is set to status: "error" and drawn with the error placeholder icon (packages/element/src/renderElement.ts:387).
localStorage quota exceeded (QuotaExceededError)saveDataStateToLocalStorage excalidraw-app/data/LocalData.ts:73-109, isQuotaExceededError LocalData.ts:111-120A red "localStorageQuotaExceeded" banner (excalidraw-app/App.tsx:1078-1082), set through localStorageQuotaExceededAtom and cleared on the next successful save. The scene stays in memory but is no longer persisted. Sentry's ignoreErrors filters this error out.
IndexedDB unavailableLocalData.ts saveFiles and getFiles, packages/excalidraw/data/library.ts:840-970Images fail per file (error placeholder). Library load and migration failures are logged, and the library falls back to the store it already has. A failed library save shows "saveLibraryError" once the editor is loaded. Sentry ignores "Internal error opening backing store for indexedDB.open".
AI request fails or is rate-limitedexcalidraw-app/components/AI.tsx:84-160, packages/excalidraw/components/TTDDialog/hooks/useTextGeneration.ts:140-290For diagram-to-code, a 429 renders an inline "Too many requests today" page, and any other error sets the frame's generation status to error (packages/excalidraw/components/App.tsx:2985). For text-to-diagram, the chat shows the error message and the rate-limit counters. A new request aborts the one in flight.
An element fails to renderlogElementRenderError packages/excalidraw/renderer/staticScene.ts:68-80Nothing. That element is skipped for the frame and the rest of the scene draws. The error is logged with the element id and bounds, which in production reaches Sentry.
An uncaught render errorTopErrorBoundary excalidraw-app/components/TopErrorBoundary.tsx:12-110The whole app is replaced by an error splash with three actions: reload, clear the canvas (empty localStorage and reload), or open a GitHub issue prefilled with the Sentry event id. componentDidCatch sends the exception to Sentry.

Retries, timeouts and idempotency

Retries. The application code has no automatic retry with backoff. Collaboration relies on three things instead. First, socket.io-client's own reconnection. Second, a full-scene rebroadcast every 20,000 ms (SYNC_FULL_SCENE_INTERVAL_MS, in queueBroadcastAllElements), which repairs dropped messages. Third, a fallback load from Firestore on connect_error or when no initial scene arrives within 5,000 ms. A file that fails to upload is not retried (FileManager.ts:107). cacheMermaidChunks is the one deliberate retry: if prefetching fails it clears its guard, so the next opening of the dialog tries again.

Timeouts. No fetch call to the JSON backend, Firebase Storage, the library backend or the AI backend carries a timeout. INITIAL_SCENE_UPDATE_TIMEOUT is the only timer that stands in for one. The AI requests can be aborted through an AbortController, but only when the user cancels or a newer request replaces the old one, never on a timer.

Idempotency. Applying the same collaboration update twice is harmless. reconcileElements keeps the local copy of an element unless the remote copy has a higher version, and breaks a tie by the lower versionNonce (shouldDiscardRemoteElement, packages/excalidraw/data/reconcile.ts:23-71). saveToFirebase runs inside a Firestore transaction that reconciles the stored scene before writing, so two clients saving at once do not overwrite each other's elements.

Failure isolation. Isolation is local. Per-element rendering errors, per-file upload and load errors, and per-font load errors (packages/excalidraw/fonts/Fonts.ts:319) are each contained. Font subsetting drops from its worker to the main thread after the first worker failure (packages/excalidraw/subset/subset-main.ts:49). There are no dead letters or circuit breakers, which is expected for a single-page client.

What is swallowed

The evidence counts 14 empty or comment-only error handlers in non-test source. Its list stops after ten ("and 4 more"), so the table below names all 14 as found in the source. Most guard optional browser features where failure has a safe default. The ones a user would notice are the clipboard copy in CustomStats and the share sheet in shareRoomLink: both fail with no message.

HandlerEnclosing codeWhat is swallowed
packages/element/src/elementLink.ts:101parseElementLinkFromURLA string that does not parse as a URL; returns null.
packages/element/src/embeddable.ts:502matchHostnameAn unparseable embed URL ("// ignore"); returns null, so the embed is not allow-listed.
packages/common/src/utils.ts:1232getFeatureFlagUnreadable or malformed feature flags in localStorage; the defaults apply.
packages/common/src/editorInterface.ts:204loadDesktopUIModePreferencelocalStorage read errors, for example in Safari private mode.
packages/common/src/editorInterface.ts:217persistDesktopUIModelocalStorage write errors; the UI mode is not remembered.
packages/excalidraw/clipboard.ts:552parseClipboardClipboard text that is not Excalidraw JSON; it is pasted as plain text.
packages/excalidraw/components/App.tsx:1128onWindowMessageA non-JSON postMessage from the YouTube or Vimeo player origin.
packages/excalidraw/components/TTDDialog/MermaidToExcalidraw.tsx:233Mermaid auto-fix effectErrors while probing auto-fix candidates for a broken Mermaid definition ("ignore auto-fix probe errors").
packages/excalidraw/subset/woff2/woff2-bindings.ts:1040demangleC++ name demangling errors in generated Emscripten glue.
packages/excalidraw/subset/woff2/woff2-bindings.ts:4001checkUnflushedContentErrors flushing stdout at exit in generated Emscripten glue.
excalidraw-app/App.tsx:199Module-level self-embedding checkAn unparseable document.referrer ("// ignore"); the app assumes it is not embedded in itself.
excalidraw-app/CustomStats.tsx:69CustomStatsA failed copy of the version string to the clipboard; no toast and no error.
excalidraw-app/share/ShareDialog.tsx:100shareRoomLinkAny failure of the browser's Web Share call, including the user cancelling ("Just ignore.").
scripts/stats/perf.mjs:621checkOutRemoving a git worktree that was never created, at process exit (CI tooling only).

The swallowing goes further than these 14 handlers, in two ways. First, many handlers log and continue, so whether a failure is noticed depends on Sentry being on. In Docker builds it is off (VITE_APP_DISABLE_SENTRY=true). Second, Sentry's ignoreErrors list (excalidraw-app/sentry.ts:26-32) drops quota-exceeded errors, closing-IndexedDB errors, "Failed to fetch" and failed dynamic imports. That keeps the noise down, but it also hides an outage of a backend reached by fetch.

Functions named in this section 39 rows
FunctionWhereWhat it does
TopErrorBoundaryexcalidraw-app/components/TopErrorBoundary.tsx:12A React error boundary around the whole app. On a render error it reports to Sentry and shows a splash with reload, clear-canvas and report-issue actions.
componentDidCatchexcalidraw-app/components/TopErrorBoundary.tsx:26Captures the exception with Sentry, keeps the event id and a parsed copy of localStorage, and switches the boundary into its error state.
exportToBackendexcalidraw-app/data/index.ts:248Compresses and encrypts the scene, posts it to the JSON backend, uploads its images to Firebase Storage, and returns the share URL or an error message.
onExportToBackendexcalidraw-app/App.tsx:771The app's share-link export handler. It calls exportToBackend, stores the link for the dialog, and rethrows any error message so the export dialog shows it.
encodeFilesForUploadexcalidraw-app/data/FileManager.ts:228Compresses and encrypts each image for upload, and throws if any encoded file is larger than the given byte cap.
importFromBackendexcalidraw-app/data/index.ts:202Fetches a share-link payload by id, then decrypts and decompresses it into elements and app state. It alerts the user and returns an empty result on failure.
legacy_decodeFromBackendexcalidraw-app/data/index.ts:170Decodes share links written in the old format, first with an IV prefix and then with a fixed all-zero IV.
startCollaborationexcalidraw-app/collab/Collab.tsx:492Opens a collaboration session: pauses local saves, connects the socket, registers the Firestore fallbacks, and wires up the socket listeners.
fallbackInitializationHandlerexcalidraw-app/collab/Collab.tsx:533A closure that loads the room scene from Firestore through initializeRoom when the socket fails or no peer sends the scene in time.
initializeRoomexcalidraw-app/collab/Collab.tsx:725Clears the fallback timer and listener and, when asked, loads and decrypts the stored scene from Firestore. Errors are logged so peers can supply the scene instead.
socketIOClientsocket.io-client (dependency)The Socket.IO client factory, loaded lazily, that opens the WebSocket (or polling) connection to the collaboration server.
saveCollabRoomToFirebaseexcalidraw-app/collab/Collab.tsx:334Saves the room's syncable elements to Firestore and merges back what was stored. On failure it sets the error indicator and opens the dialog once per message.
queueSaveToFirebaseexcalidraw-app/collab/Collab.tsx:1001A trailing-edge throttle that calls saveCollabRoomToFirebase at most once every 20,000 ms, once the socket is initialised.
queueBroadcastAllElementsexcalidraw-app/collab/Collab.tsx:987A throttle that rebroadcasts every element, deleted ones included, at most every 20,000 ms, so peers that missed a message converge.
saveToFirebaseexcalidraw-app/data/firebase.ts:190Inside a Firestore transaction, decrypts the stored room scene, reconciles it with the local elements, and writes the re-encrypted result.
saveFilesToFirebaseexcalidraw-app/data/firebase.ts:144Uploads encrypted file buffers to Firebase Storage under a prefix with a cache max-age of 31,536,000 s, and returns which ids were saved and which failed.
loadFilesFromFirebaseexcalidraw-app/data/firebase.ts:277Fetches and decrypts image files from Firebase Storage by id, and marks any that fail to fetch or decode as errored.
saveFilesexcalidraw-app/data/FileManager.ts:92Picks the scene's image files that are not yet saved or being saved, saves them through the injected saver, and records each as saved or errored.
getFilesexcalidraw-app/data/FileManager.ts:139Loads files by id through the injected loader, reports a loading, loaded or error status for each, and records which failed.
queueFileUploadexcalidraw-app/collab/Portal.tsx:104A 300 ms throttle that saves new image files and then marks their elements saved, so collaborators know to fetch them.
updateImageCachepackages/excalidraw/components/App.tsx:10624Loads image files into the editor's image cache and sets any image element whose file failed to load to status: "error".
saveDataStateToLocalStorageexcalidraw-app/data/LocalData.ts:73Writes the non-deleted elements and the cleaned app state to localStorage, and raises or clears the quota-exceeded flag.
isQuotaExceededErrorexcalidraw-app/data/LocalData.ts:111Recognises a storage-quota DOMException by any of the names or codes different browsers use.
logElementRenderErrorpackages/excalidraw/renderer/staticScene.ts:68Logs a rendering error with the element's id, position and size, so one broken element does not stop the frame.
reconcileElementspackages/excalidraw/data/reconcile.ts:73Merges remote elements into the local list, keeping whichever copy of each element wins, and preserves the order.
shouldDiscardRemoteElementpackages/excalidraw/data/reconcile.ts:23Decides whether a remote element loses: the local copy is being edited, has a higher version, or wins the versionNonce tie-break.
cacheMermaidChunksexcalidraw-app/data/cacheMermaidChunks.ts:21Five seconds after the text-to-diagram dialog opens, fetches every Mermaid chunk so the service worker caches them. It resets itself on failure so it can try again.
parseElementLinkFromURLpackages/element/src/elementLink.ts:94Returns the element id from a URL's element-link query parameter, or null.
matchHostnamepackages/element/src/embeddable.ts:473Checks an embed URL's hostname against one or a set of allowed hostnames, ignoring a leading www, and returns the match or null.
getFeatureFlagpackages/common/src/utils.ts:1222Returns a feature flag value, reading the flags once from localStorage and falling back to the defaults.
loadDesktopUIModePreferencepackages/common/src/editorInterface.ts:194Reads the saved desktop UI mode ("compact" or "full") from localStorage, or returns null.
persistDesktopUIModepackages/common/src/editorInterface.ts:211Saves the desktop UI mode to localStorage.
parseClipboardpackages/excalidraw/clipboard.ts:523Turns clipboard data into Excalidraw elements and files when it holds Excalidraw JSON, and into plain text otherwise.
onWindowMessagepackages/excalidraw/components/App.tsx:1117Handles postMessage events from embedded YouTube and Vimeo players and tracks their playback state.
demanglepackages/excalidraw/subset/woff2/woff2-bindings.ts:1023Emscripten-generated helper that turns a mangled C++ symbol into a readable name for error messages.
checkUnflushedContentpackages/excalidraw/subset/woff2/woff2-bindings.ts:3989Emscripten-generated helper that flushes any buffered stdout when the WebAssembly module exits.
CustomStatsexcalidraw-app/CustomStats.tsx:36The app's extra rows in the stats panel: storage sizes and a version row that copies the build version when clicked.
shareRoomLinkexcalidraw-app/share/ShareDialog.tsx:93Opens the operating system's share sheet with the collaboration room link.
checkOutscripts/stats/perf.mjs:606Checks out a revision into a temporary git worktree for the perf comparison, and removes it again at process exit.

Error handling and resilience rating

Error handling and resilience: 6/10, Fair

Fair. The approach is deliberate. Errors are caught at the call and shown to the user, console.error reaches Sentry, a top-level error boundary catches render crashes, a 20,000 ms full rebroadcast heals dropped collaboration messages, Firestore is the fallback when the socket fails, and reconciliation by element version makes rebroadcasts idempotent. The real gaps: no retry with backoff, a failed file upload is never retried, backend fetches have no timeout, a failed share-link import surfaces as window.alert, and 14 handlers swallow errors silently.

14. Availability and recovery

The editor is a static PWA: once loaded and cached by the service worker it draws and saves offline, so the editing path has no server dependency. The Workbox worker generated by the VitePWA plugin (registerType: "autoUpdate" in excalidraw-app/vite.config.mts) precaches the app shell and caches fonts, locales and chunks at run time (§11), and the scene is saved to localStorage and IndexedDB in the tab. Only the shared features (share links, live rooms, images in either, AI, library publishing) need a server, and each of those servers is a single external service named by one URL in .env.production.

There is no HA topology to describe from this repository. Nothing here provisions, replicates or load-balances any of the services the app calls; the Docker image is one nginx container serving static files with restart: on-failure in docker-compose.yml.

Single points of failure

Single pointWhat depends on itWhat stops when it is downWhat keeps working
Collaboration serverLive rooms: startCollaboration opens a Socket.IO connection to VITE_APP_WS_SERVER_URL (oss-collab.excalidraw.com).No live rooms: no element updates, cursors, idle status or follow mode between peers.On connect_error, or when no scene arrives within 5,000 ms, a joiner falls back to the last Firestore copy through initializeRoom and loadFromFirebase. The local canvas keeps working; socket.io-client retries the connection on its own.
Share-link JSON backendEvery share link: exportToBackend POSTs to it and importFromBackend GETs from it.No new links, and old links cannot open, since the scene exists only there.Exporting a .excalidraw file or an image, which never leaves the browser.
Firebase projectRoom persistence in the Firestore scenes collection, and images in rooms and links in the Storage bucket (project excalidraw-room-persistence).No room persistence or images in rooms and links: a joiner with no peer online sees an empty room, and images fail to upload or load (those that cannot be loaded are marked with the error status).Peers already connected keep exchanging elements over the socket; images already in a browser's IndexedDB still display there.
AI backendText-to-diagram chat and diagram-to-code, streamed from VITE_APP_AI_BACKEND (oss-ai.excalidraw.com).Text-to-diagram and diagram-to-code stop.Mermaid-to-Excalidraw conversion, which runs in the browser from a lazily loaded chunk.
Vercel hostingServing excalidraw.com, its staging and preview hosts.First visits fail, as does any browser without the service worker installed; no new release reaches users.Cached PWA users keep working: the shell loads from the precache and drawing, saving and file export need no server.
Browser storageEvery local drawing: localStorage holds the scene, IndexedDB the images and library.A user's local drawings exist only in that browser profile, with no server copy. Clearing site data, a private window, another device or browser eviction loses them, and a full quota stops saving.A quota failure is caught and shown as a banner (the quota-exceeded flag in LocalData), and the canvas keeps working in memory. The only backup is the user exporting a file.

The other external services are not single points of failure for drawing: the library backend stops only library publishing, the library site stops only browsing for libraries, Sentry stops only error reporting, and Simple Analytics stops only event counting. None of the external services is described in this repository, so their redundancy cannot be read here.

Backup, restore and recovery targets

No backup or restore is defined in the repository for Firestore, Storage or the JSON backend, and no RTO or RPO is stated anywhere. The Firebase rules and index files in firebase-project/ are not deployed by any workflow, so even the project's configuration could only be restored by hand. For a user, the closest thing to a backup is saving the scene as a .excalidraw file. The app guards against losing unsaved work on exit: on beforeunload it flushes the debounced local save and asks the user to stay while images are still being saved, and, during collaboration, while the room is not yet saved to Firestore (unless VITE_APP_DISABLE_PREVENT_UNLOAD is "true").

Deployment safety

Vercel's own rollback is outside the repository. The Docker image is published only as excalidraw/excalidraw:latest, so there is no earlier tag to roll back to. npm is the one channel with history: each automatic release gets a hash-suffixed version under tag next, so an embedding application can pin an earlier one. Because the service worker updates automatically, a bad release also reaches returning users on their next load, not only first-time visitors.

Detection and disaster recovery

Detection: Sentry only, no alerting. Sentry runs on excalidraw.com, staging.excalidraw.com and vercel.app hosts and is switched off in Docker builds; any alert rules live in Sentry's console, not here. The Dockerfile's HEALTHCHECK checks only that nginx answers, and docker-compose.yml disables it. Nothing checks the health of the collaboration server, JSON backend, AI backend or Firebase. No second region or account is described for any of them.

ConcernWhat the repository shows
Single points of failureSix, above; every shared feature depends on one external service.
BackupNone for Firestore, Storage or the JSON backend; user file export only.
Restore, RTO and RPONo restore procedure; no RTO or RPO stated.
Deployment safety (rollback)Vercel rollback outside the repository; Docker latest only; npm versions pinnable.
Detection and alertingSentry error reporting on hosted builds; no alerting and no backend health checks.
Disaster recoveryNo second region or account described.
FunctionWhereWhat it does
startCollaborationexcalidraw-app/collab/Collab.tsx:492Starts or joins a room: pauses local saving, opens the Socket.IO connection and registers the Firestore fallback for a failed connection.
initializeRoomexcalidraw-app/collab/Collab.tsx:725Removes the fallback listener and, when asked to fetch, loads the room's scene from Firestore; a failure is logged and left for peers to fill.
loadFromFirebaseexcalidraw-app/data/firebase.ts:252Gets a room's document by id and returns its decrypted, restored elements, or null when the room has no document.
LocalDataexcalidraw-app/data/LocalData.ts:124Saves the scene to localStorage and images to IndexedDB on a 300 ms debounce, and raises the quota-exceeded flag when localStorage is full.
exportToBackendexcalidraw-app/data/index.ts:248Compresses and encrypts the scene, POSTs it to the JSON backend, uploads its images to Storage, and returns the share URL or an error message.
importFromBackendexcalidraw-app/data/index.ts:202Fetches and decrypts a share link's scene by id; on failure it shows an alert and returns an empty scene.

Availability and recovery rating

Availability and recovery: 5/10, Fair

Fair. The editor is an offline-capable PWA whose core path needs no server, which is a strong availability design for drawing. But every shared feature depends on a single external service the repository does not describe, no backup, restore, RTO or RPO is written down for Firestore, Storage or the JSON backend, and the Docker image is published only as latest, leaving nothing to roll back to. Detection is Sentry alone, with no alerting or health checks of the backends, and local drawings have no server copy.

15. Performance and scale

Almost all the work Excalidraw does happens in the user's browser, on one tab's main thread. "Scale" therefore means two things: how large a scene one tab can draw and edit smoothly, and how many collaborators a room can hold before the sync traffic and the Firestore save become the bottleneck. Nothing on the server side of collaboration (the Socket.IO relay, Firestore, Storage) is in this repository, so its capacity cannot be read from here. Section 12 covers those services.

Hot paths

One row per path that runs often enough, or on enough data, to decide how the app feels. Each function named here is described in the table at the end of this section.

Hot pathWhat keeps it fastWhere
Canvas renderingThree stacked canvases: a static one for committed elements, an interactive one for selection, handles and cursors, and one for the element being drawn. A change to the selection or cursor redraws only the interactive canvas. Static renders go through renderStaticSceneThrottled, one throttleRAF per canvas, so a burst of changes draws at most once per animation frame. Element shapes come from the ShapeCache WeakMap via generateElementShape, so rough.js only regenerates a shape when the element object changes. The app opts into throttling by setting window.EXCALIDRAW_THROTTLE_RENDER = true (excalidraw-app/App.tsx:156), which isRenderThrottlingEnabled honours on React 18 and later.packages/excalidraw/renderer/staticScene.ts:610-670, packages/element/src/shape.ts:87-170, packages/excalidraw/reactUtils.ts:38-60, packages/excalidraw/components/canvases/
Pointer interactionPointer events are handled synchronously in the App class: handleCanvasPointerDown (App.tsx:7547) attaches window-level move and up listeners, and onPointerUpFromPointerDownHandler (App.tsx:9469, 852 lines) finishes every kind of drag, resize, bind and draw. Nothing moves this work off the main thread. What keeps it responsive is that a drag mutates elements in place and leaves drawing to the throttled renderer. App is the single 11,516-line class in packages/excalidraw/components/App.tsx.packages/excalidraw/components/App.tsx
Collaboration syncOnly changed elements are broadcast. broadcastScene sends an element only if its version is higher than the last version sent, and broadcastElements skips the send when the scene version has not risen. Cursor positions go out as volatile messages (dropped rather than queued when the socket is busy), throttled to 33 ms (CURSOR_SYNC_TIMEOUT) in onPointerUpdate. A full rebroadcast and a Firestore save each run at most every 20,000 ms (queueBroadcastAllElements, queueSaveToFirebase). Every payload is encrypted with AES-GCM before it is sent.excalidraw-app/collab/Portal.tsx:142-182, excalidraw-app/collab/Collab.tsx:943-1013
Local saveLocalData.save is debounced by 300 ms (SAVE_TO_LOCAL_STORAGE_TIMEOUT). It checks isSavePaused first, without the debounce, and skips the save while a collaboration session holds the lock or while the tab is hidden. Images go to IndexedDB, only the ones not already saved. Images unused for 24 hours and not in the scene are pruned.excalidraw-app/data/LocalData.ts:125-172
Font subsettingOn SVG and PNG export, fonts are cut down to the glyphs the scene uses by WebAssembly builds of HarfBuzz and woff2. subsetWoff2GlyphsByCodepoints runs this in a pool of Web Workers and falls back to the main thread for good after the first worker failure. The WebAssembly chunks are loaded only when an export needs them.packages/excalidraw/subset/ (subset-main.ts, harfbuzz/, woff2/), packages/excalidraw/workers.ts
Bundle loadingHeavy features are lazy chunks: the Firebase SDK, socket.io-client, Mermaid, CodeMirror, locales and fonts. The Workbox service worker precaches the core bundle, skipping any file over 2.3 MB, and caches lazy chunks, fonts and locales at runtime. Mermaid chunks are left out of the precache and fetched on demand by cacheMermaidChunks once the text-to-diagram dialog is opened.excalidraw-app/vite.config.mts:308-395, excalidraw-app/data/cacheMermaidChunks.ts

Concurrency model

The editor runs on a single browser main thread. React state updates, pointer handling, element mutation, shape generation, reconciliation of remote updates, and encryption through the async Web Crypto API all share it. Two kinds of work leave the main thread. Font subsetting goes to a Web Worker pool (packages/excalidraw/workers.ts). The minimap renders in a worker through OffscreenCanvas when the browser supports it (packages/excalidraw/components/Minimap/minimap-controller.chunk.ts), and falls back to the main thread when the worker fails. Network I/O (socket, fetch, Firestore) is asynchronous and does not block. Tabs coordinate through version keys in localStorage rather than through a shared worker. When a tab regains focus or becomes visible, it waits 50 ms (SYNC_BROWSER_TABS_TIMEOUT) and reloads the scene from storage if another tab wrote a newer version (excalidraw-app/App.tsx:595-676).

Caching

Four caches matter. In memory, ShapeCache holds rough.js shapes per element, and the editor's image cache holds decoded images per file id. In the browser, IndexedDB keeps image files across sessions. The service worker keeps the precached bundle plus runtime caches for fonts (1,000 entries, 90 days), locales (50 entries, 30 days), "chunk" (50 entries, 90 days) and "lazy-chunks" (200 entries, 90 days). On the server side, images uploaded to Firebase Storage carry a Cache-Control max-age of 31,536,000 s (FILE_CACHE_MAX_AGE_SEC), which is safe because file ids never change.

Known limits

One row per limit the source states. None is an element-count or room-size limit: the repository states neither.

LimitValueWhereWhat happens when it bites
FILE_UPLOAD_MAX_BYTES4 MiB per encoded imageexcalidraw-app/app_constants.ts:12A share link or collaboration upload with a larger image throws, and the user sees the size error. Images under the cap still count toward the JSON backend's request size, which returns RequestTooLargeError when the scene is too large.
localStorage quotaBrowser-defined, typically about 5 MB per originexcalidraw-app/data/LocalData.ts:73-120The scene stops being saved locally, and the quota banner shows (localStorageQuotaExceededAtom). Images are not affected, since they live in IndexedDB.
SYNC_FULL_SCENE_INTERVAL_MS20,000 msexcalidraw-app/app_constants.ts:6Sets both how long a peer can stay out of sync after a dropped message and how often the whole scene is re-sent and saved in a Firestore transaction. Each full broadcast costs time in proportion to the scene size, and nothing caps it.
CURSOR_SYNC_TIMEOUT33 ms (about 30 updates per second)excalidraw-app/app_constants.ts:8Each client sends at most 30 cursor messages a second. With N collaborators each client receives up to 30 times (N - 1) messages a second, and each one is decrypted and applied to React state.
SAVE_TO_LOCAL_STORAGE_TIMEOUT300 msexcalidraw-app/app_constants.ts:2A crash within 300 ms of the last change loses that change. Each save serialises the whole scene to JSON, so very large scenes pay that cost on every pause in editing.
maximumFileSizeToCacheInBytes2.3 MBexcalidraw-app/vite.config.mts:394Any build file over 2.3 MB is left out of the service worker precache, so it is not available offline until runtime caching picks it up.
lazy-chunks maxEntries200 entries, 90 daysexcalidraw-app/vite.config.mts:382-392Past 200 cached lazy chunks the oldest are evicted. Offline, an evicted chunk (for example a Mermaid diagram type) fails to load.

Load evidence

Two pieces of load evidence exist, both in CI. First, size-limit runs on every pull request to master (.github/workflows/size-limit.yml), with budgets in packages/excalidraw/.size-limit.json (340 kB for the main bundle, 290 kB for locales, 900 kB for vendor chunks). Those budgets name dist/excalidraw.production.min.js and dist/excalidraw-assets/, but the package build writes dist/prod and dist/dev, so the check may not be measuring the current output. Second, stats.yml runs on every push to master. It posts bundle stats, and it runs scripts/stats/perf.mjs, which builds this commit and the one before it, loads each in Playwright Chromium six times, alternating between them, and times page loads plus panning and zooming a large scene. The results go to the Excalidraw+ admin's Performance page. They are posted, not gated: a regression does not fail the build. The repository states no element-count limit, no room-size limit and no target frame time.

Functions named in this section 17 rows
FunctionWhereWhat it does
renderStaticSceneThrottledpackages/excalidraw/renderer/staticScene.ts:647Schedules a static-canvas render through that canvas's own animation-frame throttle, so only the latest request in a frame is drawn.
throttleRAFpackages/common/src/utils.ts:198Wraps a function so that calls within one animation frame collapse into a single call with the latest arguments.
isRenderThrottlingEnabledpackages/excalidraw/reactUtils.ts:38Returns true when the host page has set window.EXCALIDRAW_THROTTLE_RENDER and React is version 18 or later. If the flag is set on an older React, it warns once and returns false.
ShapeCachepackages/element/src/shape.ts:87A static cache, keyed weakly by element object, of the rough.js shape generated for each element and the theme it was generated for.
generateElementShapepackages/element/src/shape.ts:124Returns an element's cached shape, or generates and caches it. Exports always regenerate the shape and do not cache it.
Apppackages/excalidraw/components/App.tsx:593The editor's root React class component. It owns the scene, the app state, the canvases, and every pointer, keyboard and clipboard handler.
handleCanvasPointerDownpackages/excalidraw/components/App.tsx:7547Starts any canvas interaction on pointer down: decides what was hit, sets up the pointer state, and attaches the move and up listeners for the drag.
onPointerUpFromPointerDownHandlerpackages/excalidraw/components/App.tsx:9469Builds the pointer-up handler that finishes whatever the drag was doing (draw, move, resize, bind, erase, select) and commits it to history.
broadcastSceneexcalidraw-app/collab/Portal.tsx:142Sends the elements whose version has risen since they were last sent (or all of them when asked), records the versions sent, and queues file uploads.
broadcastElementsexcalidraw-app/collab/Collab.tsx:971Broadcasts an update only when the scene version is above the last one sent or received, then queues the periodic full rebroadcast.
onPointerUpdateexcalidraw-app/collab/Collab.tsx:943A 33 ms throttle that broadcasts the local cursor position and button state when fewer than two pointers are down.
queueBroadcastAllElementsexcalidraw-app/collab/Collab.tsx:987A throttle that rebroadcasts every element at most every 20,000 ms, so peers that missed a message converge.
queueSaveToFirebaseexcalidraw-app/collab/Collab.tsx:1001A trailing-edge throttle that saves the room to Firestore at most once every 20,000 ms.
LocalData.saveexcalidraw-app/data/LocalData.ts:144Checks whether saving is paused and, if not, calls the 300 ms debounced save that writes the scene to localStorage and new images to IndexedDB.
isSavePausedexcalidraw-app/data/LocalData.ts:169Returns true when the tab is hidden or a lock (collaboration) is holding local saves.
subsetWoff2GlyphsByCodepointspackages/excalidraw/subset/subset-main.ts:21Cuts a woff2 font down to the given code points in a worker pool, falling back to the main thread, and returns it as a base64 data URL.
cacheMermaidChunksexcalidraw-app/data/cacheMermaidChunks.ts:21Five seconds after the text-to-diagram dialog opens, fetches every Mermaid chunk at low priority so the service worker caches them for offline use.

Performance and scale rating

Performance and scale: 8/10, Good

Good. The hot paths are engineered on purpose: static and interactive canvases render separately with throttling, shapes are cached, collaboration broadcasts only changes and batches cursors at 33 ms, local saves are debounced, chunks load lazily behind Workbox caching, and fonts are subset in WebAssembly. There is load evidence: size-limit on every pull request, and a perf benchmark (scripts/stats/perf.mjs) compared against the previous commit on every push to master. It falls short of 9 for two reasons: the 11,516-line App class concentrates interaction on one main thread, and no stated element-count or room-size limit marks where the 20,000 ms full-scene rebroadcast and the Firestore transaction start to hurt.

16. Observability

All of Excalidraw's observability lives in the browser. The repository holds no server, so there is nothing for it to emit server logs, metrics or traces from. What it can see is limited to what happens in a user's tab and is then reported to Sentry. The collaboration server, the JSON backend, the AI backend and Firebase are observed, if at all, by whoever runs them, and nothing in this repository shows how.

Signals

The evidence's signal table, reproduced in full, one row per signal, absent ones included. The matches and files columns are the evidence's counts. A match shows the signal exists, not that anything reads it.

SignalPresentMatchesFilesWhere it goesWhat it covers
Loggingyes27497The browser's developer console in the user's own tab. In production, every console.error also goes to Sentry, because captureConsoleIntegration is set to the "error" level (excalidraw-app/sentry.ts:33-36). console.warn, console.info and console.log go nowhere else.The 274 console calls in 97 files: caught errors in collaboration, Firebase, share links, clipboard, fonts, the library store, history deltas and rendering (see section 13), plus warnings for recoverable conditions. The logs are not structured, carry no correlation id, and are not collected anywhere: below error level, they exist and nothing reads them.
Metricsno00None. Simple Analytics product events (trackEvent forwarding to window.sa_event, packages/excalidraw/analytics.ts) are usage analytics, not operational metrics. They cover only the categories command_palette, export and ai, and fire only when VITE_APP_ENABLE_TRACKING is "true", which the build:app script sets on the command line.Nothing operational. No request rates, latencies, error rates, room counts or socket counts are measured.
Tracingno00None. Sentry's tracing integration is not configured (no tracesSampleRate in excalidraw-app/sentry.ts).Nothing. A request from the browser to the JSON backend, Firebase or the AI backend cannot be followed past the browser.
Error reportingyes4610Sentry, via @sentry/browser with the DSN hardcoded in excalidraw-app/sentry.ts:22. It is enabled only when the hostname contains excalidraw.com, staging.excalidraw.com or vercel.app and VITE_APP_DISABLE_SENTRY is not "true". The Docker build sets it to "true" (build:app:docker), so self-hosted copies report nothing. Releases are tagged with VITE_APP_GIT_SHA. On a push to the release branch, sentry-production.yml creates the Sentry release and uploads sourcemaps from ./build/static/js/. The Vite build writes them to excalidraw-app/build, under assets/, so production stack traces are likely unmapped.Uncaught exceptions; render crashes caught by TopErrorBoundary (componentDidCatch sends them explicitly); and every console.error, which beforeSend turns into a "ConsoleError" event with a stack. beforeSend also strips the URL fragment, so share-link and room keys are not sent. The ignoreErrors list drops quota-exceeded errors, closing-IndexedDB errors, failed IndexedDB opens, "Failed to fetch" and failed dynamic imports.
Alertingno00Nothing in the repository. Any Sentry alert rules or notification routes live in Sentry's console and cannot be read from here.Nothing that the repository defines.
Health checksyes11The Dockerfile's HEALTHCHECK CMD wget -q -O /dev/null http://localhost, which only checks that nginx serves the static page. docker-compose.yml, the evidence's one match, sets healthcheck: disable: true, so the compose setup runs with no health check at all.Only that the static files are served. There are no health checks of the external backends. The closest signal is the browser's online and offline events, which set isOfflineAtom during collaboration (excalidraw-app/collab/Collab.tsx:220-270) and tell the user, not an operator.

Who would notice a failure, and how soon

FailureWho noticesHow long
A front-end crash or a caught error on excalidraw.comSentry receives the event, and whoever watches the Sentry project sees it.Seconds after a user hits it. Turning that into a page depends on alert rules outside the repository, and an unmapped stack trace slows the diagnosis.
The collaboration server, the JSON backend, the AI backend or Firebase is downOnly users, and Sentry indirectly through client errors such as a failed Firestore save, a failed share-link export, or an AI request error that reaches console.error. Plain network failures ("Failed to fetch") are in Sentry's ignoreErrors, so a fully unreachable backend can produce little or no signal.As long as it takes a user to report it. Nothing in the repository watches these services.
A self-hosted Docker copy failsOnly the person running it. Sentry is off in that build and compose disables the health check.Unbounded.
A performance or bundle-size regressionThe perf and bundle stats from stats.yml, posted to the Excalidraw+ admin pages on every push to master (see section 15), and the size-limit comment on pull requests.One CI run after the merge, if someone reads the dashboard. Neither check fails the build.
FunctionWhereWhat it does
trackEventpackages/excalidraw/analytics.ts:12Sends a product analytics event to Simple Analytics, but only for the three allowed categories, outside development, and when tracking is enabled at build time.
beforeSendexcalidraw-app/sentry.ts:39Sentry's last hook before sending. It removes the URL fragment from the event, and gives console-error events an exception with a stack trace built from the call sites.
TopErrorBoundaryexcalidraw-app/components/TopErrorBoundary.tsx:12A React error boundary around the whole app. It reports render crashes to Sentry and shows a recovery splash.
componentDidCatchexcalidraw-app/components/TopErrorBoundary.tsx:26Captures the render exception with Sentry and keeps the event id so the user can quote it in a GitHub issue.

17. Redundant code

The evidence lists 60 candidates: 8 groups of duplicate bodies and 52 functions whose name appears only at their definition. Each was checked against the source. Two tests decide whether a candidate is redundant. First, does anything in this repository call it, including through a package index that re-exports it? Second, could a caller outside the repository reach it through a published entry point? A function re-exported by an export * from a published package index is public API, so it was dropped even if nothing here calls it. So were a copy that exists so that a standalone example does not import editor internals, a method React or Next.js calls by convention, and a debugging helper meant to be called by hand. One more item, invisible to the probes, was found in the source.

19 items are kept. Six are copies of a body elsewhere: two are test helpers, one is a build script, two are documentation-site components, and one is in the editor. Twelve are functions with no caller that no package entry point exports. One is a constant declared and never read. 42 candidates are dropped, each with its reason. Removing the kept items would not change what the system does, and none of them is on a hot path.

Items kept

Redundant code, kept after checking 19 rows
CodeFile and linesWhat it doesWhat makes it redundant
handleDragFinishedpackages/excalidraw/components/Stats/MultiDimension.tsx:438-469After a width or height drag in the stats panel ends, if the dragged element is a frame, it recomputes which elements belong to the frame and clears the frame highlight.A copy of the same 32-line body at packages/excalidraw/components/Stats/Dimension.tsx:287-318. Both files are in the same package, and the shared module packages/excalidraw/components/Stats/utils.ts already exists, so one definition could serve both.
Featuredev-docs/src/components/Homepage/index.js:37-49Renders one card of the documentation site's homepage: an icon, a title and a description.A copy of dev-docs/src/components/Homepage/index.tsx:45-57. dev-docs/src/pages/index.tsx imports @site/src/components/Homepage, which resolves to only one of the two files, so the other file's components are never loaded. The site configuration does not override webpack's extension order, so which file is dead follows Docusaurus's default resolution.
HomepageFeaturesdev-docs/src/components/Homepage/index.js:51-63Renders the documentation homepage's row of feature cards from a fixed list.A copy of dev-docs/src/components/Homepage/index.tsx:59-71, in the same file pair as Feature. Only one of the two files is resolved by the import.
checkpointpackages/excalidraw/tests/contextmenu.test.tsx:32-43Test helper that snapshots the render count, the app state, every element and the history under a named checkpoint.A copy of packages/excalidraw/tests/regressionTests.test.tsx:44-55. It is in tests only, and could move to the shared test helpers.
getViewportpackages/excalidraw/tests/wheel.test.tsx:72-76Test helper that returns the editor's current scroll position and zoom.A copy of packages/excalidraw/tests/pan.test.tsx:32-36. It is in tests only.
createESMRawBuildscripts/buildUtils.js:56-62Runs the esbuild development build into dist/dev (with sourcemaps) and the minified production build into dist/prod.A copy of scripts/buildBase.js:44-50. The two scripts differ only in the getConfig, buildDev and buildProd helpers each defines (aliases, Sass and font plugins for @excalidraw/utils), so one parameterised script could replace both. This is duplication, not dead code: build:esm in packages/utils runs buildUtils.js, and five packages run buildBase.js.
getCircleAndPerpendicularLineIntersectionsAtPointpackages/laser-pointer/src/math.ts:54Returns the two points at a given radius from a point, perpendicular to a direction on either side.No caller anywhere in the repository. The package index re-exports ./state and, from ./math, only the type Point (export type { Point } from "./math"), so no consumer of @excalidraw/laser-pointer can reach it.
ButtonIconCyclepackages/excalidraw/components/ButtonIconCycle.tsx:5A button that shows the current option's icon and moves to the next option on each click.No caller and no import anywhere. The library index (packages/excalidraw/index.tsx) does not export it.
Paragraphpackages/excalidraw/components/Paragraph.tsx:1Renders its children in a <p> with the class "excalidraw__paragraph" and an optional inline style.No caller and no import anywhere. It is not exported from the library index.
isDefaultFontpackages/excalidraw/components/FontPicker/FontPicker.tsx:82Returns whether a font family id is one of the editor's default font families.No caller anywhere. It is not exported from the library index.
dataURLToFilepackages/excalidraw/data/blob.ts:300Decodes a base64 data URL into a File with the data URL's MIME type.No caller anywhere. The library index exports other names from data/blob (index.tsx:454, 529) but not this one.
base64ToArrayBufferpackages/excalidraw/data/encode.ts:60Decodes a base64 string into an ArrayBuffer, using Node's Buffer when it is available and atob in the browser.No caller anywhere. It is not exported from the library index.
isDraggablepackages/excalidraw/components/App.toolDrag.ts:113A static method of AppToolDrag that returns whether a tool type is one of the tools that can be dragged from the toolbar onto the canvas.No caller anywhere, inside AppToolDrag or outside it. The class is internal to the editor.
toObjectpackages/excalidraw/errors.ts:76A method of RequestError that returns the error's name, HTTP status and message as a plain object.No caller anywhere. RequestError is used only as a type and an error value in the text-to-diagram code, and is not exported from the library index.
getSelectionBoxShapepackages/utils/src/shape.ts:153Returns an element's selection box, padded and rotated with the element, as a polygon.No caller anywhere. packages/utils/src/index.ts does not re-export ./shape, and the package's "./*" export maps deep paths to type declarations only, so no consumer can import the function.
segmentIntersectRectangleElementpackages/utils/src/shape.ts:364Returns the points where a line segment crosses a rectangle element's edges, optionally after inflating the rectangle by a gap.Same as getSelectionBoxShape: no caller, and not reachable through the package exports. Its own comment says "TODO: Replace with final rounded rectangle code".
ellipseFocusToCenterpackages/utils/src/shape.ts:509Returns the distance from an ellipse's centre to either focus.Same as getSelectionBoxShape: no caller, and not reachable through the package exports.
ellipseExtremespackages/utils/src/shape.ts:517Returns the four points of a rotated ellipse that lie furthest along the x and y axes.Same as getSelectionBoxShape: no caller, and not reachable through the package exports.
OAI_API_KEYpackages/common/src/constants.ts:575A key name in EDITOR_LS_KEYS, the localStorage key "excalidraw-oai-api-key".Declared and never read. No code reads, writes or removes this key. The probes look for functions, so they did not report it. A browser that stored an OpenAI key under it in an earlier version still holds it, and nothing clears it.

Candidates dropped

Most dropped candidates are exports of @excalidraw/common, @excalidraw/element and @excalidraw/math. Each package's index re-exports the defining module with export *, so these functions are published API with possible callers in other repositories. That they are unused inside this monorepo is worth knowing, but deleting them would be a breaking change, not a cleanup.

Candidates dropped, with the reason 42 rows
CodeWhereWhat it doesWhy it is not redundant
debounceexamples/with-script-in-browser/utils.ts:58-85Returns a debounced function with flush and cancel, the same body as packages/common/src/utils.ts:168-195.A deliberate copy. The example is a standalone app that depends only on the published @excalidraw/excalidraw package and imports nothing from the monorepo's internal packages.
withBatchedUpdatesexamples/with-script-in-browser/utils.ts:87-94Wraps an event handler so React batches the state updates it makes, the same body as packages/excalidraw/reactUtils.ts:10-17.A deliberate copy, for the same reason as debounce.
setFeatureFlagpackages/common/src/utils.ts:1238Sets a feature flag in memory and saves the flags to localStorage.Published API of @excalidraw/common (export * from ./utils). It is also the way to set the flags getFeatureFlag reads, for example from the console.
selectNodepackages/common/src/utils.ts:274Selects all the contents of a DOM node in the window's text selection.Published API of @excalidraw/common.
removeSelectionpackages/common/src/utils.ts:284Clears the window's text selection.Published API of @excalidraw/common.
isFullScreenpackages/common/src/utils.ts:330Returns whether the document element is in browser full-screen mode.Published API of @excalidraw/common.
exitFullScreenpackages/common/src/utils.ts:336Leaves browser full-screen mode.Published API of @excalidraw/common.
supportsEmojipackages/common/src/utils.ts:516Draws an emoji on a scratch canvas to test whether the platform renders colour emoji.Published API of @excalidraw/common.
arrayToMapWithIndexpackages/common/src/utils.ts:598Builds a map from each element's id to the element and its index in the array.Published API of @excalidraw/common.
getBindingSideMidPointpackages/element/src/binding.ts:3168Returns the midpoint of the side of a bindable element that a fixed-point binding attaches to.Published API of @excalidraw/element (export * from ./binding).
getRectangleBoxAbsoluteCoordspackages/element/src/bounds.ts:521Converts a box given as x, y, width and height into its two corner coordinates.Published API of @excalidraw/element.
isLeftDifferentpackages/element/src/delta.ts:320A static method of Delta that returns whether the first object has any key whose value differs from the second.A public static method of the exported Delta class, published by @excalidraw/element.
getInnerDifferencespackages/element/src/delta.ts:418A static method of Delta that returns the sorted keys both objects share whose values differ.A public static method of the exported Delta class.
getElementsIntersectingFramepackages/element/src/frame.ts:146Returns the elements whose outline crosses a frame's edge.Published API of @excalidraw/element.
groupsAreAtLeastIntersectingTheFramepackages/element/src/frame.ts:206Returns whether any element of the given groups lies inside a frame or crosses its edge.Published API of @excalidraw/element.
groupsAreCompletelyOutOfFramepackages/element/src/frame.ts:227Returns whether every element of the given groups lies wholly outside a frame.Published API of @excalidraw/element.
editGroupForSelectedElementpackages/element/src/groups.ts:123Returns app state that enters editing of the selected element's outermost group.Published API of @excalidraw/element.
headingIsVerticalpackages/element/src/heading.ts:67Returns whether an arrow heading points up or down.Published API of @excalidraw/element.
getFramesIncludingDeletedpackages/element/src/Scene.ts:163A method of Scene that returns all frames, deleted ones included.A public method of the exported Scene class.
mapElementspackages/element/src/Scene.ts:254A method of Scene that replaces each element with the result of a function and reports whether anything changed.A public method of the exported Scene class.
isEphemeralpackages/element/src/store.ts:466A static type guard of StoreIncrement for increments that are not recorded in history.A public static method of an exported class, and the counterpart of isDurable, which is used.
getMinCharWidthpackages/element/src/textMeasurements.ts:274Returns the narrowest measured character width cached for a font.Published API of @excalidraw/element.
cartesian2Polarpackages/math/src/angle.ts:21Converts a point's x and y into a radius and an angle in radians.Published API of @excalidraw/math (export * from ./angle).
curveCatmullRomQuadraticApproxPointspackages/math/src/curve.ts:336Approximates a Catmull-Rom spline through the given points with quadratic Bezier segments.Published API of @excalidraw/math.
offsetPointsForQuadraticBezierpackages/math/src/curve.ts:414Returns the points of a quadratic Bezier curve offset sideways by a distance.Published API of @excalidraw/math.
pointRotateDegspackages/math/src/point.ts:149Rotates a point around a centre by an angle given in degrees.Published API of @excalidraw/math.
rangeInclusiveFromPairpackages/math/src/range.ts:22Brands a start and end pair as an inclusive range.Published API of @excalidraw/math.
rangeIncludesValuepackages/math/src/range.ts:78Returns whether a number lies within an inclusive range.Published API of @excalidraw/math.
rectangleFromNumberSequencepackages/math/src/rectangle.ts:13Builds a rectangle from minimum and maximum x and y values.Published API of @excalidraw/math.
rectangleIntersectLineSegmentpackages/math/src/rectangle.ts:19Returns the points where a line segment crosses the four edges of a rectangle.Published API of @excalidraw/math.
rectangleIntersectRectanglepackages/math/src/rectangle.ts:32Returns whether two axis-aligned rectangles overlap.Published API of @excalidraw/math.
lineSegmentRotatepackages/math/src/segment.ts:57Rotates a line segment by an angle around an origin, by default its midpoint.Published API of @excalidraw/math.
perfWrappackages/common/debug.ts:141A static method of Debug that wraps a function to time each call in the console.A debugging tool meant to be called by hand while profiling. Debug is exported from @excalidraw/common for that purpose.
logChangedpackages/common/debug.ts:157A static method of Debug that logs which keys of a named object changed since the last call.A debugging tool meant to be called by hand, like perfWrap.
debugDrawCubicBezierpackages/element/src/visualdebug.ts:97Queues a cubic Bezier curve to be drawn on the visual debug canvas.A visual debugging helper called by hand. It is published at the @excalidraw/element/visualdebug subpath, which excalidraw-app/components/DebugCanvas.tsx reads.
debugDrawBoundspackages/element/src/visualdebug.ts:189Queues one or more bounding boxes to be drawn on the visual debug canvas.A visual debugging helper called by hand, at the published visualdebug subpath.
debugDrawPointspackages/element/src/visualdebug.ts:224Queues each of an element's points, offset by its position, to be drawn on the visual debug canvas.A visual debugging helper called by hand, at the published visualdebug subpath.
debugCloseFramepackages/element/src/visualdebug.ts:241Starts a new frame in the visual debug buffer so later draws appear separately.A visual debugging helper called by hand, at the published visualdebug subpath.
debugClearpackages/element/src/visualdebug.ts:245Empties the visual debug buffer.A visual debugging helper called by hand, at the published visualdebug subpath.
componentDidCatchexcalidraw-app/components/TopErrorBoundary.tsx:26Reports a render error to Sentry and switches the top-level boundary to its error splash.A React lifecycle method. React calls it when a child throws while rendering, so it is never named at a call site.
getSnapshotBeforeUpdatepackages/excalidraw/components/App.tsx:4275Before the DOM updates, marks a zen-mode transition when zen mode is about to change, so the transition styles are in place.A React lifecycle method that React calls before each commit.
RootLayoutexamples/with-nextjs/src/app/layout.tsx:1The Next.js example's root layout, wrapping every page in its html and body tags.A Next.js App Router convention: the framework calls the default export of app/layout.tsx.

18. What was deliberately not drawn

Every figure in this document had to show something the source cannot: a relationship that crosses a boundary the call graph does not follow, such as a hop to a server, a postMessage between frames, or a step a user takes. The seven diagram types below were considered and rejected on that test.

Diagram typeWhy it was not drawn
class diagramThe code is React components and TypeScript types, not a class hierarchy. The few classes (App, Scene, Store, History, ActionManager, Collab, Portal) are shown by the call graph in §5, and a diagram of the 6,705 nodes in the graph would show nothing the source does not.
entity-relationship diagramNo store is relational. Every store is key-value (a Firestore document per room, Storage paths, localStorage keys, IndexedDB keys), so the key table in §11 says everything an ER diagram would.
control-flow flowchartThe code is already that flowchart; drawing the branches of the app's scene loader or of the pointer handlers would restate the source.
full call graph of App.tsxAn 11,516-line file holding one class with an 852-line pointer-up handler; a complete graph would be unreadable, so §5 draws only the backbone edges verified in graphdata.json.
in-process sequence diagramsAction to Store to History to onChange happens synchronously in one thread with no boundary crossed; §6 draws only flows that leave the tab.
state diagram of the active toolappState.activeTool is a value any tool can be set to from any other, not a machine with named transitions; drawing it would invent structure.
cloud deployment diagram of the backendsThe collaboration server, JSON backend, AI backend and Firebase infrastructure are not in this repository; drawing their internals would be guesswork, so §10 shows them as opaque external boxes.

What was drawn instead is thirteen figures, each of which crosses a boundary the source alone does not show: the business process in §2 (the user's view, which no reading of the code produces); the module dependency graph in §4, pasted unchanged from the generated figure; two layered call graphs in §5 (the app shell, collaboration and persistence down to encryption, and the editor core from pointer input down to shape generation); four sequences in §6 (share link export and import, a live collaboration session, the Excalidraw+ iframe export handshake, and the AI streaming request), each of which leaves the browser tab; the three state machines in §7 whose states the code names (collaborator idle state, image element status, diagram-to-code generation); the trust boundaries in §8; and the deployment topology in §10.

Absences carried into the assessment

Every absence the sections state, one line each, with the section that states it. This document records what is and is not there; whether an absence matters is a risk and operations question, and the technical assessment answers it. Each absence below gets a severity and a risk register entry in its §11, the operational gaps (deploys, rollback, backups, alerting, ownership) are weighed in §8, and the order to fix them in is §12.

Download