Falcon Flowmira
Technical Documentation

Excalidraw Integration Evaluation — Falcon Flowmira

Excalidraw Integration Evaluation — Falcon Flowmira

Companion PRD to the Master PRD v10. Records the review, decision, and MIT-compliant integration path taken to embed Excalidraw as the secondary whiteboard engine.

Decision Summary

  • Verdict: Adopt Excalidraw for the free-form whiteboard mode (kind='excalidraw'); keep the native React Flow engine for structured diagrams (kind='flow').
  • Rationale: Excalidraw is the best-in-class open-source hand-drawn whiteboard; rewriting is wasteful. React Flow remains superior for BPMN/UML/network/agentic flows with typed connectors and layout algorithms.
  • License: MIT — compatible with Falcon Flowmira's commercial distribution.
  • Attribution: Recorded in THIRD_PARTY_NOTICES.md; UI credit line rendered inside the whiteboard editor.

Integration Rules

  1. Lazy-mount only in browser (ClientOnly + React.lazy), never during SSR.
  2. Persist via Falcon-native diagrams table with kind='excalidraw'; do not use Excalidraw's built-in server APIs.
  3. Autosave every 1.5s with debounce; explicit checkpoints on user command.
  4. Library imports (.excalidrawlib) route through the SVG sanitizer.
  5. No Excalidraw branding hijack — the UI is Falcon Flowmira; Excalidraw is credited, not marketed.
  6. Exports use Excalidraw's official exportToSvg / exportToBlob helpers, then are stamped with Flowmira metadata.
  7. Realtime collaboration on Excalidraw boards flows through the same use-collab.ts protocol so cursors/presence match diagrams.
  8. Feature-gating identical to diagrams (Free = 3 boards, Pro / Pro Plus unlimited).

Non-Goals

  • Do not fork Excalidraw. Track upstream and pin known-good versions.
  • Do not embed Excalidraw+ hosted collaboration.
  • Do not migrate structured diagrams into Excalidraw — they belong on the React Flow engine.

Security

  • Import pipeline sanitises SVG (src/lib/security/svg-sanitizer.ts) before any user content lands in the scene.
  • No external network calls made by Excalidraw runtime; asset loading is blocked at CSP level.
  • Any user-provided text is passed through redactSecrets before persistence in diagrams.document.
  • Realtime channel names are scoped to diagram:<id>; RLS on diagram_ops enforces owner + share role.

Metrics

  • Load size impact: measured at build time; Excalidraw is code-split behind the whiteboard route.
  • Time-to-interactive on first whiteboard open: target < 1500 ms on cold cache.