NoteSync — Requirements

Personas

  • Solo writer — uses NoteSync as a private notebook, syncing across her iPhone and Mac.
  • Couple — shares a single “Household” folder for shopping lists and shared planning.
  • Team of 5 — a writing group sharing a “Drafts” folder with read-write permission and a “Published” folder with read-only permission for reviewers.

User stories

Account & onboarding

  1. First launch requires Sign in with Apple only if the user wants sharing; otherwise the app works locally + private CloudKit only.
  2. The first screen explains the privacy model: notes live in the user’s iCloud, never on third-party servers.
  3. iCloud account status is checked on launch; if signed out, the app shows a clear “Sign in to iCloud in Settings” banner.

Notes & folders

  1. Users can create unlimited notes and unlimited folders.
  2. Notes have rich text (bold, italic, lists, links), a title, a created/modified timestamp, and optional tags.
  3. Folders can be nested one level deep (no folder-of-folders-of-folders for v1).
  4. Search is full-text across all notes the user has access to (private + shared).

Sharing — sender

  1. From any note or folder context menu, “Share…” presents UICloudSharingController (iOS) or the macOS equivalent.
  2. The sender can choose read-only vs read-write permission.
  3. The sender can choose “anyone with link” vs “only invited people.”
  4. Sharing generates a https://www.icloud.com/share/... URL that opens NoteSync on the recipient’s device.

Sharing — recipient

  1. Tapping a share link with NoteSync installed opens the app and adds the shared item to a “Shared with me” section.
  2. Tapping a share link without the app shows a screen pointing to the App Store.
  3. Recipients with read-only permission see a lock icon on the note and cannot edit.
  4. Recipients with read-write permission can edit; changes propagate to all participants within ~5 s.

Conflict resolution

  1. If two users edit the same note simultaneously, the app reconciles automatically with a three-way merge.
  2. If the three-way merge is impossible (both changed the same paragraph), the app keeps both versions and shows a “Conflicts (2)” banner the user can resolve.
  3. The user can choose between the two versions, or merge manually.

AppIntents

  1. Shortcuts shows: “Create Note”, “Append to Note”, “Find Notes”, “Open Note by Title”.
  2. Each intent’s parameters use NoteSync’s EntityQuery so the user can pick from a list of real notes.
  3. Siri can invoke “Create a note saying [text]” without launching the app.
  4. Spotlight indexes all note titles and bodies; tapping a result deep-links into the note.

macOS

  1. The macOS app uses the same Swift package core as iOS. Only the views differ.
  2. macOS adds: menu bar shortcuts (⌘N new note, ⌘F search), a sidebar selection (folders | shared | tags), and inline drag-and-drop reordering.
  3. macOS supports universal clipboard from iOS without modification.

Acceptance criteria

  • Cold launch (iOS): < 1.5 s
  • Cold launch (macOS): < 1.5 s
  • Sync latency, simultaneous edits, two devices on same WiFi: < 5 s
  • Conflict resolution UI appears within 2 s of receiving a server token mismatch
  • Spotlight reindex on note save: < 500 ms
  • App size: < 25 MB

Non-goals

  • No collaboration cursors (no “Susan is typing”). v2.
  • No comments. v2.
  • No web access — Apple’s CloudKit JS is a separate world.
  • No version history beyond the last conflict resolution point.
  • No end-to-end encryption beyond what CloudKit provides (CloudKit uses transport + at-rest encryption; we don’t add a separate layer).

Constraints

  • iOS 17+, macOS 14+
  • Apple Developer Program (CloudKit + Sign in with Apple capabilities)
  • All shared zones use a single CloudKit container

Next: Architecture