Moving a notes library between iPhones without a server or iCloud

Michael Lynx — Fri, 23 Oct 2026 16:46:51 +0000

I work on Diple, a Markdown writing app with a local document library. This article looks at one part of its implementation: moving that library between devices.

The transfer needs to preserve more than text files. Documents can have local images, notes and version history. Folders and Collections also carry relationships that need to survive the move.

Here are the protocol and import decisions in the current design, including the limits of its duplicate handling.

Separate the connection from the transfer

The existing transport uses Multipeer Connectivity. Both devices advertise and browse for the same service, and the user selects a peer and confirms the connection.

The session is configured to require encryption:

let session = MCSession(peer: peerID, securityIdentity: nil, encryptionPreference: .required)

That configuration does not replace peer selection or user consent. Connecting the devices and agreeing to transfer a particular batch are separate steps.

For a new implementation, review Apple's networking API guidance and local network privacy requirements against your deployment targets. This post describes an existing implementation rather than prescribing a transport for every app.

Send a manifest before sending files

Small JSON messages, sent reliably, handle transfer requests, acceptance, the manifest, skipped items, cancellation and completion. Document packages travel separately through sendResource(at:withName:toPeer:withCompletionHandler:).

The manifest describes:

Folders in parent-before-child order.
Documents, with temporary IDs, destination folder references, filenames, text hashes, sizes and sort positions.
Collections and their references to those documents.

Before resolving destinations, the receiver checks item counts, identifier uniqueness, supported document extensions and folder relationships. It also checks that filenames are valid.

Temporary IDs identify items within a transfer. They are not filesystem paths supplied by the sender.

Keep related document data in one package

Each document is encoded as a binary property-list package containing its text, creation and modification dates, optional note, local images and version-history data.

This gives the receiver one resource to associate with a document. It does not make importing the entire library an atomic operation: documents are installed as their resources arrive, and the batch has no whole-library rollback.

Cancellation and import failures therefore need explicit handling. A stopped batch cannot automatically be interpreted as having changed nothing.

Define what counts as a duplicate

The receiver first resolves the intended destination path. If a document already exists at that path and its text hash matches the incoming descriptor, the document resource is skipped.

That is a path-scoped comparison, not a search for matching text anywhere in the library.

Situation	Current behavior
Same destination path and same text hash	Skip the document resource
Same destination path but different text	Import under an available filename
Matching text elsewhere in the library	No global deduplication based on that match
Same text but changed attachments or history	The text-based skip rule can still apply

The last row is an important limit. Equal text hashes do not establish that two complete document packages are identical. This policy is useful for an explicit transfer workflow, but it should not be mistaken for a general synchronization algorithm.

Collections have a separate rule. If the receiver already has a Collection with the same UUID, its existing Collection record is preserved. Repeating a migration does not overwrite that record to match the sender.

Distinguish delivery from import completion

The sender has a completion message for finishing resource transmission. The receiver has a separate acknowledgement after the expected, non-skipped and non-cancelled resources have finished importing.

Keeping these states separate matters: sending a file successfully and installing it in the destination library are different operations. Skipped and cancelled items also affect what a completed batch means.

For this kind of migration, the useful design questions are concrete: which items were requested, which were skipped, which were imported, and what happens to existing data on another attempt?

Those rules deserve as much attention as the connection API.