#SyncingBoard (Figma & Penpot to Miro Sync Engine)

SyncingBoard is a stateless, open-source integration tool that lets product and design teams sync design screens from Figma and Penpot directly into Miro boards as lightweight, flat images. It prevents canvas clutter by updating images in-place (zero duplicates) using metadata tagged inside Miro's native title property.

Unlike official live embeds which require browser logins and degrade board performance, SyncingBoard places fast-loading, flat images that stakeholders can annotate, draw on, and reference instantly.

#Why Stateless?

SyncingBoard is deliberately built as a stateless proxy engine for key technical, security, and operational reasons:

• Privacy-First Security Model: We never store raw Figma or Miro access tokens, credentials, or design screens on our servers. Rate limiting identifies callers using anonymous, one-way SHA-256 token fingerprints (tok:sha256(token)) from which original access tokens can never be recovered. Your intellectual property remains strictly within your design tools.
• Pairing IDs Are Bearer Access Keys: A pairing ID lets anyone holding it read from an open, connected Figma/Penpot companion. For Penpot the pairing ID is the only credential (no OAuth); for Figma, imports/syncs additionally require your own Figma OAuth. Treat pairing IDs like passwords, use one per board/companion pair, and disconnect companions when done — see Security & Pairing Best Practices. An optional per-pairing passphrase (PIN) is planned for a future release.
• Third-Party Cookie Resilience: Miro plugins operate inside sandboxed browser iframes where modern browsers block third-party cookies. Storing tokens client-side within the active Miro session avoids iframe cookie restrictions entirely.
• Enterprise Compliance Exemption: Storing zero personal data or design files bypasses GDPR Data Subject Access Requests (DSARs), right-to-be-forgotten pipelines, and complex Data Processing Agreements (DPAs) for enterprise security reviews.
• Zero Infrastructure Overhead: Operating database-free allows self-hosters and design teams to deploy SyncingBoard in minutes on serverless hosts (like Vercel) with zero database management or storage costs.
• Self-Healing Serverless Scale: Serverless functions scale instantly from 0 to 10,000 requests/minute and back to 0 without database schema migrations, connection pool limits, or cold-start latency.
• Seamless Board Collaboration: Frame pairing metadata is stored directly inside Miro widget properties (title). This enables any teammate on the board to sync design updates without requiring complex multi-user database permissions.

#Features

• In-Place Updates: SyncingBoard updates Miro image widgets in place — replacing the binary content while keeping position, dimensions, rotation, and parent frames intact. No duplicates.
• Consolidated Selection & Copies Counter: Groups duplicates of the same frame under a single card with a count badge (e.g. x3). Format/scale changes apply to all copies at once.
• Replace Selected (Adopt Image): Replace any image widget — even non-SyncingBoard ones — with a SyncingBoard-managed copy, preserving connectors, comments, and frame membership.
• Preserve Widget Size: Refresh image content without resizing, keeping manual crop/scale/layout adjustments.
• Batch Limit of 3: Sync up to 3 unique frames per operation to stay within API rate limits (Community version). Warning banner appears when exceeded.
• Dual-Platform Sync: Supports Figma (cloud-native sync) and Penpot (relay-first sync) side-by-side.
• Figma & Penpot Selection Auto-Detect: Detects active selections directly from companion plugins via the cloud relay — no desktop apps required.
• Cloud Relay Transport: Public HTTPS relay (Upstash Redis + Vercel) coordinates between companions and the Miro plugin — no localhost calls, no PNA blocks, works in any browser.
• Automated Test Coverage: 123 Vitest unit and integration tests validating token security, rate-limiting logic, URL parsers, and API route handlers (yarn test).
• SyncBridge Companion (Planned Desktop Extender): Tauri-powered desktop app for future advanced capabilities — large images (>4.5MB), Adobe UXP bridge, local LLMs, two-way sync. Not required for day-to-day sync.

#Integration & Compatibility Matrix

#Deployment Modes: Community vs. Self-Hosted

SyncingBoard can be utilized in two different hosting configurations:

#Community Version (Official Market Plugins)

[!IMPORTANT] User-Owned OAuth Architecture: SyncingBoard maintains zero user databases and requires no user registration. Every user authenticates directly with their own personal Figma and Miro accounts via standard OAuth 2.0. Access tokens remain stored client-side inside the user's active Miro board session.

For quick testing and evaluation, you can use the official pre-published plugins running on the public Community infrastructure hosted at https://www.syncingboard.com.

• Zero Configuration: Simply install the official SyncingBoard Miro App to your Miro team.
• 1-Click OAuth Connect: Connect your Miro account (and your Figma account if syncing from Figma) via 1-click OAuth buttons inside the Miro sidebar. Penpot doesn't require OAuth, but connects via Pairing ID and cloud relay.
• Plug and Play: To enable selection auto-detection or Penpot sync, load the companion in Figma/Penpot, copy the Pairing ID from the Miro sidebar, and paste it into the companion to connect.
• Figma Companion Scope: The Figma Companion plugin is only needed for selection detection (auto-detecting your active selection in Figma). You can import and sync screens directly into Miro using Figma URLs without installing the companion plugin.
• Rate Limits: To keep the maintainer's shared infrastructure responsive for everyone, the Community version enforces daily rate limits on image exports and node queries.
• Fair Relay Pool: The Community relay holds 40 concurrent sessions with 1 active board per Miro user. Opening a second board shows a one-click "Transfer Session to This Board" banner that moves your active session — transparent capacity, no hidden queues. Companions get a fair pool too: a 180-token cap with a permanent 20-socket Miro reserve, 1 active tab per pairing, and orphan eviction with auto re-admission so active syncs always win.
• Setup Video Walkthroughs:
  • Figma Companion Setup: ▶ Watch on YouTube
  • Penpot Companion Setup: ▶ Watch on YouTube

#Self-Hosted Version (Private Production)

For production use inside design teams, you can deploy your own instance of SyncingBoard on Vercel or any Node.js container host.

• Customizable Sync Quotas: Since you connect your own accounts, you can bypass the shared Community rates and configure custom daily limits (or disable the rate limiter entirely by setting RATE_LIMIT_ENABLED=false) to fit your team's needs (bounded only by your own Upstash and Ably plan quotas). The relay-session and companion pools are also configurable: set RATE_LIMIT_COMMUNITY_MAX_RELAY_SESSIONS=0 and/or RATE_LIMIT_COMMUNITY_MAX_COMPANION_TOKENS=0 for unlimited pools (still bounded by your Ably connection limit).
• Custom Developer Apps: Since you run on your own domain, you will need to register your own custom developer apps:
  • Miro: Set the App URL to https://YOUR_DOMAIN.com/miro-plugin?init=true and redirect URI to https://YOUR_DOMAIN.com/api/oauth/miro/callback.
  • Figma: Register a developer app in the Figma Dev Portal to obtain a Client ID and Redirect URI pointing to your domain callback endpoint.
• Penpot: No OAuth registration needed. Penpot connects via the Pairing ID and cloud relay. See the setup guide for details.
• Companion Configuration:
  • In Figma: The companion plugin loads the hosted production companion by default — no setup. Self-hosters point it at their own domain via the optional "Preview host" field at the bottom of the plugin panel (persisted per plugin), or at compile time via the DEFAULT_HOST constant in figma-plugin/ui.html; either way the domain must be listed in the manifest's allowedDomains (devAllowedDomains for dev plugins).
  • In Penpot: Add a custom plugin in your Penpot dashboard pointing to your self-hosted companion URL (e.g., https://your-domain.com/penpot-companion-ui.html).
• Full Data Ownership: OAuth credentials, pairing states, and design image buffers are stored securely inside your private cloud infrastructure.

Deploy your own instance? Follow the full setup & deployment guide.

#Technology Stack

SyncingBoard runs on a deliberately minimal, serverless-friendly stack. Here is roughly what each piece does and why:

• Vercel — hosting & API gateway. Next.js serverless functions serve the Miro sidebar app, the REST API (OAuth, the Figma render/rate-limiting proxy), and the Figma/Penpot companion pages. Everything scales to zero when idle; there is no always-on server to maintain. Self-hosters run the same code on any Node.js host.
• Upstash — serverless Redis. The rate-limit counters (token/pairing windows plus the shared daily backstop), the relay requestId → pairingId result binding, and the concurrent Miro relay-session lease all live in Redis. Because it is serverless it needs no connection pool and scales to zero between requests.
• Ably — real-time messaging. Ably WebSockets carry the selection relay and Penpot export commands/results between companion plugins and the Miro bridge over channels like penpot:${pairingId}, and drive companion presence detection. The server never holds an open socket.
• Figma, Miro & Penpot — design-tool APIs. Your own OAuth credentials drive Figma render/export and Miro image updates; Penpot relays through its companion. SyncingBoard never stores these tokens or your designs.

Full setup & deployment guide -> doc/setup.md

Tauri/SyncBridge setup -> doc/setup.md#tauri-desktop-app-syncbridge-optional

Architecture reference -> doc/architecture.md

#License

This project is open-source and licensed under the GNU Affero General Public License v3 (AGPL-3.0). See the LICENSE file for more details.