A teaching page for a new engineer

How a note travels between devices

Reading time about 6 minutesWritten 2026-10-16For: a new engineerExample with made-up data

A note saves on your phone first, then the server numbers it, and your other devices ask for what is newer.

Keep in your head (only these)
  1. A note saves on your phone before it is sent.
  2. The server numbers every change, so the order is never in doubt.
  3. Each device asks what is new since its last number.

The four layers a note passes through

Easiest first
  1. On your phoneThe note is saved on the phone before anything is sent.Local copyOutbox
  2. On the sync serverThe server puts every change in one order.ChangeChange number
  3. On your other devicesA device asks for what is newer than the last change it saw.CursorPull
  4. When two devices disagreeThe later change wins and the other text is replaced.ConflictLast write wins

Take: a note passes through four layers, and each one adds only a few words. The chips are the words you learn there.

  1. Where does a note live first?On the phone, saved before it is sent.
  2. What does the server do with a change?It numbers the change, so the order is fixed.
  3. How does another device find out?It asks for everything after its cursor.
  4. What if two devices edit the same note?The later change wins.
  5. How can you watch it happen?Five steps with a phone and a browser.

Chapter 1 of 5, about 1 minute

Where does a note live first?

Before this: the answer says a note saves on your phone first and travels after that.

When you edit a note, the app does not wait for the network. It saves the edit to the local copy of your notes. The screen answers at once, and nothing is lost if the signal drops.

Next the app adds the edit to the outbox. A background task sends the outbox in order whenever the phone is online. In a lift, the outbox waits.

Local copy
The notes stored on the phone itself. The app reads and writes this copy first.
Outbox
The edits the phone has saved but not yet sent. It empties as the server confirms each one.
You edit a note. The edit is saved to the local copy at once and added to the outbox. Later, when there is a connection, the outbox goes to the sync server. 1. You edittype in the app 2. Local copysaved at once 3. Outboxedits waiting to go 4. Sync servergets them when online Steps 1 to 3 work with no connection needs a connection You edit a note. The edit is saved to the local copy at once and added to the outbox. Later, when there is a connection, the outbox goes to the sync server. 1. You edittype in the app 2. Local copysaved at once 3. Outboxedits waiting to go 4. Sync servergets them when online Steps 1 to 3 work with no connection
Take from this: saving and sending are two separate steps. The first is instant, and the second happens when it can.

The outbox is a tray of letters on your desk. You write each letter now, and the post collects them later, in order. Where it stops: the app collects its own tray the moment there is a connection.

Show one outbox row

Each edit is one row. The phone keeps it until the server confirms it.

outbox row 1
  note id     n_7f3a
  text        Milk, eggs
  edited at   2026-10-16 09:12:04
  tries       0

Remember: a note saves on the phone at once, and its edit waits in the outbox until the network is back.

Chapter 2 of 5, about 1 minute

What does the server do with a change?

Before this: an edit sits in the phone's outbox until the phone is online.

The phone sends each edit to the sync server as a change. The server writes it down and gives it the next change number for your account: 41, then 42, then 43.

Sync server
The one program, run by us, that every device of yours talks to.
Change
One saved edit, packed to send: the note's id, its new text and when you made it.
Change number
The server's running count of changes for your account. Change 42 always comes after change 41.

Phones, tablets and the web app all feed the same list. The server never asks which device was first. The order of arrival is the order.

A phone, a tablet and the web app send changes to the sync server. The server writes them into one change log and numbers them 41, 42 and 43 in the order they arrive. Devices sendThe server's change log Phone Tablet Web app Sync servernumbers each changeas it arrives 41Phone: Groceries 42Web app: Trip ideas 43Phone: Groceries A phone, a tablet and the web app send changes to the sync server. The server writes them into one change log and numbers them 41, 42 and 43 in the order they arrive. Phone Tablet Web app Sync servernumbers each change as it arrives 41Phone: Groceries 42Web app: Trip ideas 43Phone: Groceries
Take from this: one list with one order. No device has to guess which edit came first.
Show the request and the reply

The phone posts one change. The server answers with the number it gave it.

POST /v1/changes
{ "note": "n_7f3a", "text": "Milk, eggs", "edited": "09:12:04" }

201 Created
{ "change": 41 }

Remember: the server numbers each change as it arrives, and that number fixes the order.

Chapter 3 of 5, about 1 minute

How does another device find out?

Before this: every change has a number, and the server keeps the changes in order.

Your laptop does not wait to be told. It asks every 10 seconds, while the app is open: what is new since the last number I saw? That number is its cursor. The question is a pull.

Cursor
The last change number a device has applied. The device stores it.
Pull
A device asking the server for what is new. The server never pushes.

The server answers with every change after that number, in order. The device applies them one by one. Then it moves its cursor to the last number it received.

The laptop's cursor is 41. It asks the server for anything after 41. The server answers with changes 42 and 43. The laptop applies them and its cursor becomes 43. Laptopcursor: 41 Sync serverhas changes up to 43 1. Anything after 41? 2. Yes: changes 42 and 43 Laptopcursor: 43 3. It applies 42 and 43 in order, then remembers 43. The laptop's cursor is 41. It asks the server for anything after 41. The server answers with changes 42 and 43. The laptop applies them and its cursor becomes 43. Laptopcursor: 41 1. Asks: anything after 41? Sync serverhas changes up to 43 2. Answers: changes 42 and 43 Laptopcursor: 43 3. It applies 42 and 43 in order,then remembers 43.
Take from this: the device keeps its own place. Asking again with the same cursor gets the same answer.
Show the question and the answer

The cursor travels in the address. The reply lists the changes and the newest number.

GET /v1/changes?after=41

200 OK
{ "latest": 43,
  "changes": [
    { "change": 42, "note": "n_2c91", "text": "Trip ideas" },
    { "change": 43, "note": "n_7f3a", "text": "Milk, eggs" } ] }

Remember: a device is never pushed to, and it asks for everything after its cursor.

Chapter 4 of 5, about 1 minute

What if two devices edit the same note?

Before this: a device asks for the changes after its cursor and applies them in order.

Sometimes two devices change the same note before either hears from the server. That is a conflict. Version 2.3 settles it with one rule: the higher change number wins.

Conflict
Two edits to the same note that neither device knew about.
Last write wins
The rule that the change with the higher number replaces the other change's text.

Later means later to arrive, not later typed. A laptop that typed at 09:10 and was offline reaches the server after a phone that typed at 09:12. The laptop's text wins.

The note Groceries says Milk after change 40. The phone types Milk, eggs at 09:12 and sends it first as change 41. The laptop typed Milk, bread at 09:10 while offline and sends it second as change 42. The server keeps change 42, so the eggs are replaced. Groceries after change 40Milk Phone, typed 09:12Milk, eggs. Sent first: change 41. Laptop, typed 09:10, offlineMilk, bread. Sent second: change 42. Server keeps change 42Milk, bread. The eggs are replaced. The higher number wins, even though the laptop typed first. The note Groceries says Milk after change 40. The phone types Milk, eggs at 09:12 and sends it first as change 41. The laptop typed Milk, bread at 09:10 while offline and sends it second as change 42. The server keeps change 42, so the eggs are replaced. Groceries after change 40Milk Phone, typed 09:12Milk, eggs. Arrives first: change 41. Laptop, typed 09:10, offlineMilk, bread. Arrives next: change 42. Server keeps change 42Milk, bread. The eggs are replaced.
Take from this: the order of arrival decides, not the time on the clock. The loser's text is replaced.
What this costs

In 2.3 the replaced text is not kept. A shared notebook could lose a teammate's words. Mara and Ted are deciding whether 2.4 keeps both copies.

Remember: when two edits clash, the one that reaches the server last wins, and the other text is replaced.

Chapter 5 of 5, about 1 minute

How can you watch it happen?

Before this: a note is saved, sent, numbered, pulled and, in a clash, replaced.

You need your phone and a browser, both signed in to the same test account. The steps take five minutes.

  1. Open the web app and the phone app. Sign in to the same test account on both.
  2. Turn on airplane mode on the phone. The app keeps working.
  3. Edit the note called Groceries. Add "eggs" at the end.
  4. Open More, then Sync details. It shows one edit waiting to send.
  5. Turn airplane mode off. Within 10 seconds the count drops to 0 and the web app shows "eggs".
Airplane mode
A phone setting that turns off every connection, so the app is offline.
Sync details
The screen under More that shows the outbox count and the last change number the phone has seen.
The Sync details screen with airplane mode on shows 1 edit waiting to send. After airplane mode is turned off, the same screen shows 0 waiting and a newer change number. Sync details: offline Waiting to send1 Last change seen4,182 Last sync09:02 airplanemode off Sync details: online Waiting to send0 Last change seen4,183 Last sync09:05 The Sync details screen with airplane mode on shows 1 edit waiting to send. After airplane mode is turned off, the same screen shows 0 waiting and a newer change number. Sync details: offline Waiting to send1 Last change seen4,182 Last sync09:02 airplane mode off Sync details: online Waiting to send0 Last change seen4,183 Last sync09:05
Take from this: the outbox count is the proof. It reads 1 while the phone is offline and 0 once the server has the edit.
Try a clash on purpose

Repeat the steps, with one change at step 3. Edit Groceries in the browser first, then on the phone.

  1. Keep airplane mode on. Edit Groceries on the phone and add "eggs".
  2. Edit Groceries in the browser. Add "bread" and wait for it to save.
  3. Turn airplane mode off. The phone sends last, so the phone's text wins on both screens.

Remember: the outbox count on the Sync details screen shows whether an edit has left the phone.

Recap

  1. A note saves on the phone at once, and its edit waits in the outbox until the network is back.
  2. The server numbers each change as it arrives, and that number fixes the order.
  3. A device is never pushed to, and it asks for everything after its cursor.
  4. When two edits clash, the one that reaches the server last wins, and the other text is replaced.
  5. The outbox count on the Sync details screen shows whether an edit has left the phone.