04 · Offline notes that sync

• Repository — the one owner of one kind of data. It turns the server's format into the app's model. Here, the database's.
• Composite — a repository that only reads: it asks two repositories and combines their answers into one model. Not used here.
• Store — in-memory state that several screens show at once. Not needed here yet.
• Use case — one user intent with a product rule, like "only the latest tap counts". Not needed here.
• View model — the screen's brain. It owns the screen's state and hands the screen one view state.
• Policy — a product rule as a pure function: no disk, no network, no state.
• Source of truth — the one place whose answer is right: the phone's database.
• Pending change — an edit the server hasn't got. Its change ID makes a resend harmless (idempotent).
• Transaction — several writes saved together, all or none.
• Version, conflict — the server bumps a note's version on each change; a conflict is an edit of an old version.
• Tombstone, cursor — a tombstone marks a deleted note. The cursor is the server's bookmark in its changes feed.

"What's in a note?" → A title and plain text. No attachments for now.

"One device or several?" → Phone, iPad and the web, same account.

"Shared notes?" → No. One owner per note.

"Two devices edit the same note offline?" → Never lose what someone typed. How you show it is up to you.

"An edit on one device, a delete on another?" → Your call. Say what you'd pick.

"How fresh must other devices be?" → Seconds when online is nice. Minutes is fine.

"How many notes?" → Hundreds, a few KB each. Some users have ten thousand.

"How many users?" → Five million, a few dozen saves a day each. Don't design the backend.

"Minimum OS?" → iOS 17, SwiftUI, Swift 6.

Out of scope, said first: attachments, sharing, rich text, server search, the web client, how the server stores notes.

Required for the prompt

1. Create, edit and delete notes with no network.
2. Changes reach the user's other devices when online.
3. A conflict never loses text.
4. Show which notes haven't synced, and whether the last sync failed.

What must feel good: instant · durable, even if killed · each change lands once, in order · only changes are sent.

Production considerations (say, don't draw): token refresh, safe retries, data protection, metrics. Section 12.

Optional follow-ups (add only when asked):

Seconds-fresh on other devices → a silent push that starts a pull
Long notes, attachments        → diffs, separate uploads
Fewer conflict copies          → merge edits to different lines
Real-time collaboration        → a different design (CRDT or OT)

"I'll start simple and add each of these when the requirement appears."

"The phone's database is the truth, so the screen reads and writes only there. One database owns the notes and the pending changes, so a save writes both in one transaction. A sync engine sends pending changes with PUT /notes/{id} and DELETE /notes/{id}, one at a time per note, each with a change ID, then pulls other devices' changes with GET /notes/changes?since={cursor}. When the server says 'conflict', a pure conflict policy decides: keep both copies, and an edit beats a delete. Sync status is its own stream, so a failed sync reads 'not up to date', never 'no notes'."

Eight cards, two chips. Note and SyncStatus are written on cards 3 and 4.

No use case: watch, save and delete have no rule. The one rule, conflicts, is a pure policy: no user taps "resolve".

Not drawn: the HTTPClient inside card 8, and a network monitor wrapping NWPathMonitor behind a NetworkPath protocol (card 6's trigger). Not on the list yet: the optional follow-ups, a search index.

flowchart TB
  subgraph P["PRESENTATION"]
    View["`**1 · Notes screen**
NotesView`"] -- "actions → view state" --> VM["`**2 · Notes view model**
NotesViewModel`"]
  end
  subgraph D["DOMAIN"]
    NotesP["`«protocol»
NotesRepository`"]
    StatusP["`«protocol»
SyncStatusRepository`"]
    Policy["`**7 · Conflict policy**
ConflictPolicy
pure, no I/O`"]
  end
  subgraph DA["DATA"]
    Notes["`**3 · Notes repository**
LocalNotesRepository
rows → Note`"]
    Status["`**4 · Sync status repository**
LocalSyncStatusRepository
row → SyncStatus`"]
    Sync["`**6 · Sync engine**
NotesSyncEngine
app-scoped actor`"]
    DB["`**5 · Notes database**
NotesDatabase
one writer, atomic`"]
    API["`**8 · Notes API client**
NotesAPIClient
GET /notes/changes
PUT /notes/{id}
DELETE /notes/{id}`"]
  end
  VM -- "watch, save → notes" --> NotesP
  VM -- "watch → status" --> StatusP
  VM ~~~ Policy
  NotesP ~~~ Notes
  Notes -. "implements" .-> NotesP
  StatusP ~~~ Status
  Status -. "implements" .-> StatusP
  Policy ~~~ Sync
  Sync -- "conflict → decision" --> Policy
  Notes -- "save → rows" --> DB
  Status -- "watch → row" --> DB
  Sync -- "next, apply → ok" --> DB
  Sync -- "push, pull → DTOs" --> API
  class View,VM pres
  class NotesP,StatusP,Policy dom
  class Notes,Status,Sync,DB data
  class API net

How to read it. A solid arrow points from the asker to the answerer: request → reply. Dashed arrows mean implements. Only the orange card touches the network.

Dependency inversion, in one line. The domain writes the two promises (the chips); cards 3 and 4 keep them, so both dashed arrows point up.

One class, three promises. Card 5 keeps a narrow protocol per caller: NoteRecords (card 3), SyncStatusRecords (card 4), SyncRecords (card 6). That makes "one transaction" honest: note and pending change live in one database.

No shared store: list and editor are one screen; a second screen would watch the same database.

On Miro: three frames, eight cards, two chips. Point at card 6: "the screen never waits for this."

The models everyone shares. The screen never sees a record or a DTO.

struct Note: Identifiable, Hashable, Sendable {
    /// Made on the phone, so it exists offline
    let id: NoteID
    let title: String
    let body: String
    let updatedAt: Date
    /// synced, pending, or refused (the server won't take it)
    let sync: NoteSyncState
}

struct SyncStatus: Equatable, Sendable {
    /// nil = this device has never finished a sync
    let lastSyncedAt: Date?
    let isSyncing: Bool
    let lastRunFailed: Bool
}

1 · Notes screen (NotesView)

Job: shows the list and the editor, and reports what the user does. It decides nothing.

Interface: reads viewModel.viewState; calls onAppear(), select(_:), create(), edit(title:body:), delete(_:).

Choice: NavigationSplitView: side by side on iPad, pushed on iPhone, one screen.

2 · Notes view model (NotesViewModel)

Job: combines the notes and status streams into one view state, and owns the draft.

struct NotesViewState: Equatable {
    /// title, preview, formatted date, badge ("Not synced")
    let rows: [NoteRow]
    /// noNotes, firstSyncRunning, firstSyncFailed; nil when there are rows
    let empty: EmptyState?
    let isSyncing: Bool
    /// e.g. "Couldn't sync · last synced 10:42"; the rows stay
    let syncProblem: String?
    let editor: EditorState?
}

@MainActor @Observable
final class NotesViewModel {
    init(notes: NotesRepository, status: SyncStatusRepository)

    var viewState: NotesViewState { get }

    func onAppear() async
    func select(_ id: NoteID)
    func create()
    func edit(title: String, body: String)
    func delete(_ id: NoteID)
}

Choices:

• It watches, it doesn't fetch. Each stream replays its value, then every change, from this screen or from sync.
• Small states that coexist: rows, syncing and "last sync failed" at once, without a dozen enum cases.
• A failed sync is "unknown", not "empty". "No notes yet" appears only after a sync succeeded; before that, "Loading your notes…" or "Couldn't load them yet".
• The draft is the view model's until saved, debounced (half a second after typing stops, and on leaving). An incoming list never overwrites it.

3 · Notes repository (LocalNotesRepository)

Job: reads rows as Notes; turns a save or delete into one atomic database call.

protocol NotesRepository: Sendable {
    /// Replays the current notes, then each change. One stream per
    /// caller; it finishes when the caller's task is cancelled.
    func notes() -> AsyncStream<[Note]>
    /// Saves the note and its pending change, all or none. Throws
    /// only if the disk write fails. Not cancelled by the caller.
    func save(id: NoteID, title: String, body: String) async throws
    /// Marks a tombstone and queues the delete, all or none.
    func delete(_ id: NoteID) async throws
}

final class LocalNotesRepository: NotesRepository {
    init(records: NoteRecords)
}

Choices:

• save(id:title:body:), not save(_ note: Note), so a caller can't set sync or a version. Only the database decides those.
• One source, so no composite. The pending flag is a join inside one database. No "sync now": the engine notices saves.

4 · Sync status repository (LocalSyncStatusRepository)

Job: reads the status row the engine writes, as SyncStatus.

protocol SyncStatusRepository: Sendable {
    /// Replays the current status, then each change. One stream per
    /// caller; finishes when the caller's task is cancelled.
    func status() -> AsyncStream<SyncStatus>
}

final class LocalSyncStatusRepository: SyncStatusRepository {
    init(records: SyncStatusRecords)
}

Choice: its own protocol, so the notes stream carries notes only, not the engine's state.

5 · Notes database (NotesDatabase)

Job: keeps notes, tombstones, versions, pending changes, the cursor and the status row, and runs each write that must land together as one transaction.

/// Card 3's half
protocol NoteRecords: Sendable {
    func noteRows() -> AsyncStream<[NoteRecord]>
    /// Note row + its waiting change, one transaction
    func saveNote(id: NoteID, title: String, body: String) async throws
    func deleteNote(id: NoteID) async throws
}

/// Card 4's half
protocol SyncStatusRecords: Sendable {
    func statusRow() -> AsyncStream<SyncStatusRecord>
}

/// Card 6's half
protocol SyncRecords: Sendable {
    /// The "after each save" trigger
    func pendingCount() -> AsyncStream<Int>
    /// Oldest change whose note has nothing in flight, frozen
    /// with its text and base version. nil = nothing to send.
    func nextChange() async throws -> SentChange?
    func complete(_ change: ChangeID, version: Int) async throws
    func markRefused(_ change: ChangeID) async throws
    /// One transaction: server copy in, optional new note queued,
    /// the stale change dropped
    func settleConflict(_ change: ChangeID, serverCopy: NoteRecord?,
                        newNote: NoteRecord?) async throws
    /// Changes + cursor, one transaction. Skips notes with a pending
    /// change; refuses a run for another account.
    func apply(_ changes: [NoteRecord], cursor: Cursor,
               account: AccountID) async throws
    func cursor() async throws -> Cursor?
    func recordStatus(_ status: SyncStatusRecord) async throws
}

actor NotesDatabase: NoteRecords, SyncStatusRecords, SyncRecords {
    init(fileURL: URL)
}

Choices:

• One owner of the tables that change together. "Note + change" and "changes + cursor" are one transaction each only because one database runs both.
• SQLite behind one actor on iOS 17. The only writer, so it publishes after each commit. Rejected: SwiftData behind a @ModelActor has no change history on iOS 17; HistoryDescriptor is iOS 18. Switch at an iOS 18 minimum.
• Records only; cards 3, 4 and 6 map.

6 · Sync engine (NotesSyncEngine)

Job: the one background job: wake on a trigger, push pending changes one at a time, then pull.

protocol SyncEngine: Sendable {
    /// Starts the triggers: launch, network back, foreground, a newly
    /// queued change. Calling it twice changes nothing.
    func start() async
    /// Sign-out. A reply still in flight is refused by apply's
    /// account check.
    func stop() async
}

actor NotesSyncEngine: SyncEngine {
    init(records: SyncRecords, api: NotesAPI,
         policy: ConflictPolicy, network: NetworkPath)
}

Choices:

• One loop, one change at a time, oldest first: no two syncs race, and each note's changes arrive in order. Push first, then pull.
• It asks the policy, it doesn't own the rule. On a 409 it calls ConflictPolicy, then settleConflict. The DTO → record mapper is a pure helper inside it.

7 · Conflict policy (ConflictPolicy)

Job: decides what a conflict becomes. Pure: no disk, no network, no state.

enum Side: Equatable, Sendable {
    case edited(title: String, body: String)
    case deleted
}

enum ConflictResolution: Equatable, Sendable {
    /// Server copy stays the note; local text becomes a new note
    case keepBoth(copyTitle: String)
    /// The server deleted it; local text comes back as a new note
    case recreate
    /// Our delete lost to a newer edit; the note comes back
    case keepServer
}

struct ConflictPolicy: Sendable {
    /// Same input, same answer. Never throws.
    func resolve(local: Side, server: Side) -> ConflictResolution
}

Choices:

• Domain, because a PM states it without naming HTTP: "never lose text, and an edit beats a delete".
• A policy, not a use case: no user intent starts it, and it does no I/O. Tested with plain inputs.

8 · Notes API client (NotesAPIClient)

Job: calls the three endpoints and decodes the replies into DTOs.

protocol NotesAPI: Sendable {
    /// Throws on failure. Cancelling the caller cancels the request.
    func changes(since cursor: Cursor?) async throws -> ChangesPageDTO
    /// Throws .conflict(NoteDTO) on 409; the DTO says deleted: true
    /// for a tombstone. A repeated change ID gets the first answer.
    func put(_ id: NoteID, _ note: NoteBodyDTO, baseVersion: Int?,
             change: ChangeID) async throws -> Int
    func delete(_ id: NoteID, baseVersion: Int,
                change: ChangeID) async throws
}

Choices:

• A client, not a repository: it returns DTOs. A fake that answers 409 or times out tests the engine.
• Auth in its HTTP client: on a 401, refresh once and retry. Decoding is @concurrent under Swift 6.2, off the engine's actor.

Why these parts, and no more. Each card changes for one reason:

Each protocol earns a fake or a smaller promise. Not added: a use case for saving (a pass-through), a composite (one source), a shared store (the database is shared), a DI container, a CRDT library.

Flow 1 — edit offline, then the network comes back.

sequenceDiagram
  participant VM as View model
  participant N as Notes repo
  participant DB as Database
  participant S as Sync engine
  participant A as API client
  VM->>N: save(id, title, body)
  N->>DB: saveNote, one transaction
  DB-->>VM: notes, "Not synced"
  Note over S: network back
  S->>DB: nextChange()
  DB-->>S: c7, base 4, frozen
  S->>A: PUT /notes/{id}, change c7
  alt accepted
    A-->>S: version 5
    S->>DB: complete(c7, 5)
  else conflict
    A-->>S: 409, server copy
    Note over S: ConflictPolicy says keepBoth
    S->>DB: settleConflict, one transaction
  else no reply
    Note over S: keep c7, retry unchanged
  end

A timeout doesn't say whether the server saved it, so the retry is identical; the server answers a repeat with its first answer.

Flow 2 — another device changed a note.

sequenceDiagram
  participant S as Sync engine
  participant A as API client
  participant DB as Database
  participant N as Notes repo
  participant VM as View model
  S->>A: GET /notes/changes?since=cursor
  alt loaded
    A-->>S: changes, tombstones, new cursor
    S->>DB: apply(changes, cursor, account)
    Note over DB: skips notes with pending edits
    DB-->>N: new rows
    N-->>VM: new notes
  else failed
    A-->>S: error
    S->>DB: recordStatus(failed)
    Note over VM: "Couldn't sync", rows stay
  end

A failed pull applies nothing and keeps the cursor.

GET    /v1/notes/changes?since={cursor}&limit=200
       → { "changes": [ { "id", "title", "body", "version",
                          "updatedAt", "deleted": false } ],
           "nextCursor": "…", "hasMore": false }

PUT    /v1/notes/{id}   Idempotency-Key: {changeId}
       { "title", "body", "baseVersion": 4 }   // null for a new note
       → 200 { "version": 5 }
       → 409 { "note": { …server copy…, "deleted": false } }

DELETE /v1/notes/{id}?baseVersion=5   Idempotency-Key: {changeId}
       → 204, or 409 with the newer copy

• The phone makes the note ID and the change ID. PUT creates or updates; a repeated change ID gets the first answer.
• baseVersion says "I edited version 4". If the server is past it, or holds a tombstone, it answers 409.
• The cursor is opaque and the server's. Order is its promise; the client returns it untouched and ignores a change no newer than its copy. Expired: 410 Gone, full resync. Personal data, never on a shared cache.

Decision: keep both copies. The rule lives in ConflictPolicy.

1. The phone syncs first: PUT with base 4 is accepted; the note is version 5.
2. The laptop's PUT with base 4 gets 409 and the server's version 5.
3. The policy sees two edits: keepBoth. In one transaction the server's copy becomes the note, and the laptop's latest text becomes a new note, "Groceries (conflict copy)", with its own pending change.
4. The user merges by hand, if they care.

Rejected: last write wins, which silently throws away one device's typing. Later: merge edits to different lines. Out of this design: CRDTs, which solve real-time collaboration.

Decision: a tombstone, not a removed row.

1. The phone marks the note deleted, hides it, and queues a delete, in one transaction.
2. The engine sends DELETE with the base version.
3. The server keeps a tombstone and returns it in everyone's changes feed.
4. Other devices apply it: mark deleted, hide.

Why not remove the row? A pull couldn't tell "deleted here" from "never had it", and the note would return.

Edit here, delete there. The policy says an edit beats a delete:

• The delete landed first. Our PUT gets 409 with deleted: true. recreate: our text returns as a new note, new ID.
• The edit landed first. Our DELETE gets 409 with the newer copy. keepServer: the note reappears.
• Both deleted. No conflict; the server answers 204.

Cleaning up: tombstones are purged after, say, 30 days. A device offline longer gets 410 and resyncs, keeping pending changes.

Nothing is lost, and nothing is applied twice.

• After saving, before sending. Note and change were one transaction; next launch sends it.
• After the server accepted, before complete. The frozen change goes again, same change ID; the server returns its first answer. No 409, no duplicate.
• Mid-pull. Changes and cursor are one transaction, so the pull repeats.

Concurrency: database and engine are each one app-scoped actor; the view model is on the main actor.

The stale-result guard, carried by the account ID. Cancellation is cooperative, so a reply can land after sign-out; apply refuses another account's results. Inside the same transaction it also skips notes edited while the pull was out.

Sign-out with pending changes: warn ("3 notes haven't synced and will be lost"), then stop the engine, delete the database.

Background. beginBackgroundTask(withName:expirationHandler:) gives a push a little time as the user leaves. A BGAppRefreshTask from BGTaskScheduler may pull, but the system decides if and when. A bonus.

Failures

Production notes (short, not on the board)

• Networking: timeouts; retry timeouts and 5xx with backoff, safe because every write has a change ID. NWPathMonitor is a hint to try now, not a promise.
• Caching: the database is the cache.
• Metrics: save-to-ack latency, oldest pending age, sync failures, conflict rate, full resyncs. No note text in logs.
• Security: tokens in the Keychain; the database file uses completeUntilFirstUserAuthentication, because complete locks it while the phone is locked and background sync fails.

Scale, back of the envelope, with the interviewer's numbers:

notes per user × average note size        = local storage
users × saves synced a day × payload size = sync traffic

10,000 notes × 2 KB is 20 MB: fine on the phone, too much to download each launch, hence the changes feed. Five million × 30 × 2 KB is about 300 GB a day; debouncing keeps it down.

Grow only when asked

A second screen or a widget  → watches the same database, no store
Seconds-fresh across devices → a silent push that starts a pull
Ten thousand notes           → paged pulls, a lazy list
Long notes                   → send diffs, not whole bodies
Attachments                  → separate uploads, referenced from the note
Collaboration                → a different design (CRDT or OT)

Answer out loud first, then open.

Scope and architecture

Saving and the queue

Sync and the API

Conflicts and deletes

Change and scale

14+ is a pass.A zero names the thing to read about next.:::