Sources & Whiteboard Targets

Product teams rarely use a single design or whiteboard tool across the entire product lifecycle. While Figma dominates UI design, open-source engineering teams rely on Penpot, and whiteboard collaboration takes place across Miro and FigJam.

SyncingBoard solves tool fragmentation by enforcing a decoupled Source-Target architecture. Design applications act strictly as Sources (producing screen payloads), while whiteboards act strictly as Targets (rendering and pairing image widgets).

1. Design Sources (Figma & Penpot)

Design sources are responsible for extracting UI frame vectors or bitmaps and passing them to SyncingBoard’s normalization layer.

Figma Source Adapter

Figma integration operates through serverless REST API relays (/api/figma/render-batch):

• URL Parsing: figmaUrlParser.ts extracts file keys, node IDs, and frame selection parameters from standard Figma share links.
• REST API Batch Rendering: Requests node images via Figma’s /v1/images/:key API endpoint, calculating node bounding boxes, scale parameters, and high-resolution export formats (PNG or SVG).
• OAuth Security: User authorization operates via standard OAuth 2.0 with automatic token refresh (/api/oauth/refresh), storing credentials securely in client-side session memory.

Penpot Source Adapter

Because Penpot operates across self-hosted enterprise domains and cloud instances, SyncingBoard utilizes a browser companion plugin (PenpotAdapter.ts and companionRelayClient.ts):

• DOM & Vector Capture: Captures vector SVG payloads directly from Penpot’s browser Web Components.
• WebSocket Relaying: Streams export payloads via /api/relay/penpot/result through real-time session channels directly to the active whiteboard target.
• Zero-Config Gateway: Runs within the user’s active browser session to inherit existing authentication cookies without requiring OAuth app setup for self-hosted instances.

2. Whiteboard Targets (Miro & FigJam)

Whiteboard targets receive normalized image payloads, locate existing paired canvas items, and execute in-place geometry updates.

Miro Target Adapter

Operating through the Miro Web SDK v2 in MiroAdapter.ts:

• Metadata Tagging: Reads and writes native appData metadata tags containing deterministic pairing hashes (pairingId.ts).
• In-Place Swapping: Replaces image widget url properties directly without deleting canvas nodes or breaking attached comment threads.
• Geometry Preservation: Executes a snapshot+restore retry loop to maintain exact canvas coordinates, scale, and bounding-box aspect ratios.

FigJam Target Adapter

For teams using FigJam as their collaborative whiteboard target, SyncingBoard implements a dedicated adapter (FigJamAdapter.ts):

• Plugin API Mapping: Maps item title metadata and image widget payloads to FigJam’s native plugin API format.
• Canvas Alignment: Preserves widget coordinates and frame grouping bounds on FigJam canvases.

3. The Unified Payload Contract (DesignPayload)

By decoupling sources from targets, SyncingBoard transforms any design editor into any whiteboard target using a normalized intermediate contract:

// Unified payload contract bridging any Source to any Target
export interface DesignPayload {
  sourceId: 'figma' | 'penpot';
  frameId: string;
  frameTitle: string;
  svgContent?: string;
  imageUrl?: string;
  bounds: { width: number; height: number };
  pairingHash: string;
}

This decoupled pipeline guarantees that adding a new design source (e.g. Penpot) or a new whiteboard target (e.g. FigJam) requires zero changes to the underlying WebSocket relay architecture.

Continue exploring: Serverless Relay Architecture or return to SyncingBoard Overview.