Desktop Sync

Synchronize your patterns and thread inventory between the desktop app and a self-hosted Needlework Studio server.

Overview

The Needlework Studio desktop app can operate entirely offline as a standalone application, but it also supports bidirectional synchronization with a self-hosted Needlework Studio server. When sync is configured, your data flows in both directions - changes made on the desktop are pushed to the server, and changes made on the server (or from another synced desktop) are pulled to the desktop.

This means you can design patterns on your laptop, review them on your phone through the server's web interface, and track stitching progress from either device. All data stays in sync automatically.

Setting Up Sync

Pairing the desktop app with a server is a straightforward process:

1. Open the sync panel - Click the cloud icon in the desktop app's navigation bar. This opens the sync configuration panel.
2. Enter the server URL - Type the full URL of your Needlework Studio server instance (for example, https://needlework.example.com or http://192.168.1.50:6969). The URL should point to the root of the application, not to a specific page.
3. Enter your credentials - Provide the username and password for your account on the server. These credentials are used only once during the pairing process to authenticate and request an API token.
4. Pair - Click the pair button. The desktop app sends your credentials to the server, which validates them and issues an API token. This token is stored securely on the desktop and used for all subsequent sync operations.

Security Note

Your username and password are not stored on the desktop after pairing. They are sent to the server once to obtain an API token, and then discarded. Only the API token is retained. The token provides the desktop app with the ability to read and write your data on the server without needing to store your credentials. If you are concerned about token security, you can revoke it at any time by unpairing (see below).

Server Requirements

To use sync, you need a running Needlework Studio server that is accessible from the machine running the desktop app. The server can be on your local network (accessible by IP address) or exposed to the internet with a domain name. If you have not set up a server yet, see the Installation and Deployment guides.

How Sync Works

Synchronization transfers data between the desktop app and the server to keep both copies up to date.

Automatic Sync on Launch

When the desktop app starts and a server is paired, it automatically performs a sync operation. This pulls any changes from the server (such as patterns you created via the web interface) and pushes any local changes that have not yet been synced. You do not need to take any action - sync happens in the background during startup.

Manual Sync

You can trigger a sync at any time by clicking the Sync Now button in the sync panel. This is useful if you have just made changes on the server and want them to appear on the desktop immediately without restarting the app, or if you want to ensure your latest desktop changes are pushed to the server before switching devices.

What Syncs

The sync process covers all of the core data in Needlework Studio. Here is a complete list of what is synchronized between the desktop and server:

Saved Patterns

All saved patterns are synced in full, including:

• Grid data - The complete stitch grid with all full stitch placements and colors.
• Legend - The thread color legend with DMC/Anchor thread references, symbols, and color definitions.
• Part stitches - Half stitches, quarter stitches, and three-quarter stitches with their positions and orientations.
• Backstitches - All backstitch lines with start and end coordinates and thread color assignments.
• French knots - All French knot positions and their thread color assignments.
• Progress data - Per-color completion status, so your stitching progress is available on both devices.
• Thumbnails - Pattern thumbnail images for display in the gallery.
• Metadata - Pattern name, status (Not Started / In Progress / Completed), creation date, and modification timestamps.

Thread Inventory

Your thread inventory data is synced across devices, including:

• Ownership status - Whether each thread is marked as Own, Need, or Don't Own.
• Skein quantities - The number of skeins recorded for each thread.
• Notes - Any free-text notes you have attached to individual threads.

Deletions

When you delete a pattern on one device, that deletion is propagated to the other device during the next sync. The pattern will be removed from both the desktop and the server. Deletions are tracked so that a deleted pattern does not reappear from the other device's copy.

Conflict Resolution

In cases where the same piece of data has been modified on both the desktop and the server since the last sync, a conflict occurs. Needlework Studio uses a last-write-wins strategy based on modification timestamps to resolve conflicts.

When two versions of the same pattern or thread record have different modification times, the version with the more recent timestamp is kept, and the older version is overwritten. This approach is simple and predictable: the most recent change always takes precedence.

In practice, conflicts are rare if you follow a natural workflow of making changes on one device at a time and syncing regularly. If you are concerned about accidental data loss, you can fork a pattern before making major changes, which creates an independent backup copy that will not be affected by sync conflicts on the original.

Status Indicator

The sync status is communicated visually through the cloud icon in the desktop app's navigation bar. The icon changes color and animation to reflect the current state:

• Gray - Unpaired. The desktop app is not connected to any server. Sync is not configured. Click the icon to set up pairing.
• Green - Paired and idle. The desktop app is paired with a server and the last sync completed successfully. Data is up to date.
• Gold pulse - Syncing. A sync operation is currently in progress. The icon pulses with a gold animation while data is being transferred. Avoid closing the app while syncing to ensure all data is transferred completely.
• Red - Error. The last sync attempt failed. This typically means the server is unreachable (network issue, server is down, or the URL has changed). Check your network connection and server status. The icon will return to green after a successful sync.

Unpairing

If you want to disconnect the desktop app from the server, you can unpair at any time:

1. Click the cloud icon to open the sync panel.
2. Click the Unpair button.
3. Confirm the action in the dialog.

When you unpair, the following happens:

• The API token stored on the desktop is deleted.
• The token is revoked on the server, so it cannot be reused even if someone were to recover it.
• The desktop app returns to standalone mode. Your local data remains intact - nothing is deleted from the desktop. However, future changes on the server will no longer be pulled to the desktop, and local changes will no longer be pushed.

You can re-pair with the same server (or a different one) at any time by going through the setup process again. Re-pairing will issue a new API token and resume synchronization.