Calendars and to-do lists get used when the connection is at its worst. You finish a task on the subway, move next week's meeting on a plane, jot down something in an elevator. If the app says "check your connection" at that moment, people don't write it down again. So ikie accepts writes while offline. The screen updates immediately, and whatever needs to reach the server waits on the device and goes out on its own once you're connected.
Show first, send later
Every write has two steps. First we change the board on the device (the day-by-day events and tasks the app draws) so the screen shows it, then the write that needs to reach the server goes into a queue. When the server accepts it, that's it. When the server refuses it, we roll back only the days that write changed. Other days and other writes stay as they are.
On the web we didn't build a separate queue. TanStack Query's mutation cache already holds paused writes and resends them once you're back online. We persist that cache on the device so it survives a reload. On iOS the queue is one file per person. Writes made outside the app, from widgets, Siri or the share sheet, are left in the shared App Group folder, and the app picks them up into the same queue when it opens.
Only writes that can wait, wait
Not every write is safe to send later. The test is one question: is the result the same if it arrives twice?
| Write | When offline | Why |
|---|---|---|
| Done, status, flag, move, save, delete, restore, tags, RSVP | Waits | These set a value, so resending gives the same result |
| Create, one-line capture, add inside | Waits | The app picks the id. The same id creates only one item |
| Appending notes or links | Refused | Send an append twice and you get two lines |
| Do it now, fit to a time range | Refused | The server decides from the current time and what's already there |
| Settings, accounts, sharing | Refused | Not something to change later on the user's behalf |
When we refuse, the board doesn't change and we say "You can do this once you're connected". We'd rather say so than leave something that looks half done.
Sent twice, created once
Tasks created offline are the tricky part. If the request reaches the server but the connection drops on the way back, the app doesn't know whether the task was created, so it sends again. Left alone, that makes two tasks.
So the app picks the new item's id (a UUID), and the server creates an item for that id only once.
- If the id already exists and I can edit it, nothing new is created and the server returns that id.
- If the id belongs to someone else, it's refused with a 409 (
id_taken). - If two requests race to insert, the server reads again and returns the one item.
We added no new table and no Idempotency-Key header for this. The item's id itself is the key that recognizes "the same write". If you finish a task you created offline, or add a task inside it, those writes point at the same id. The create has to go first, so they line up behind it.
Every response has a decided outcome
The response to a sent write falls into one of three outcomes: sent, keep or drop.
| Response | Outcome | Why |
|---|---|---|
| Unreachable, 408, 429, 5xx | Keep | Retry after 2, 5, 15, then 60 seconds. Immediately when a reconnect signal arrives |
| 401 | Keep | The sign-in expired, nothing more. Dropping it would silently lose what you did offline |
| 404 on a delete | Sent | It's already gone, so the job is done |
| 400, 403, 404, 409 | Drop | Resending gets the same answer. Shown as not sent once everything else has gone |
When one write is dropped, later writes that point at the same item are dropped with it. If a create was refused, sending that item's "done" would get the same answer.
We set a few times too. Sometimes the device believes it's connected when it isn't, like Wi-Fi with no internet behind it. So while writes are waiting, we fetch the board every 30 seconds to check. Writes that waited more than a day aren't sent right away even after reconnecting. We ask first. If another device edited the same field in the meantime, a person should decide before a day-old value overwrites it.
Replay unsent writes on the fetched board
Writes can wait for hours. If the app fetches the board in the meantime, the server doesn't know about those writes yet, so a task you finished arrives unfinished. Swap in the fetched board as is, and the finished task looks like it came back.
So we keep the fetched board and lay the unsent writes back on top of it, in order. On both web and iOS this is a pure function, so reopening the app or flipping to another month gives the same board.
The rules once, two interpreters
All of the rules so far (which writes wait, what each response means, how long to wait, how many retries) must be identical on web and iOS. So they aren't written per platform. They're declared once as data in the app policy. The web reads them with a TypeScript interpreter, and iOS reads Swift code generated from the same declaration with a Swift interpreter.
export function outboxOutcome(kind: WriteKind, status: number | null, attempt = 0): OutboxOutcome {
const table = POLICY.outbox.outcome.value;
if (status === null) return table.network ?? "keep";
const out = table[`${status}.${kind}`] ?? table[String(status)] ?? table[`${Math.floor(status / 100)}xx`] ?? "drop";
return out === "keep" && status !== 401 && attempt >= POLICY.outbox.onlineRetries.value ? "drop" : out;
}
Both interpreters are tested against the same scenario file, with 15 cases for the queue alone. Change a rule and update only one interpreter, and the other one's tests break.
We put everything in one line, then split it up
At first every write went into one line. With a strict order, a "done" can never get ahead of the create it belongs to. Offline, that was fine. The trouble showed up online.
The day the queue shipped, the app was reported to feel sluggish, and while chasing the causes we measured the order of writes too. On an iOS simulator with a demo account, we delayed server responses to 3.4 seconds on purpose, tapped five checkboxes quickly, and timed when each write left for the server.
Show the numbers
| Build | s |
|---|---|
| Before the queue | 0.4 · 1.2 · 1.9 · 2.7 · 3.4 s |
| One-line queue | 0.5 · 4.1 · 7.6 s … |
With one line, each write waited for the previous write's round trip. The checkbox on screen flipped right away, but everything that follows the server's answer (folding finished items, closing a sheet, notifications) slipped by one round trip per write. Worse, if one write got a 5xx and was waiting to retry, every unrelated write stopped too.
So now the order is kept per item. Writes to the same item, and writes to the items it depends on (the parent it goes inside, or a prerequisite), keep their order. Different items don't wait for each other. And when the server is reachable but keeps failing a write, we retry it only twice. If it still fails, we roll the screen back and list the write as not sent. Before, retries could go on for minutes while the board stayed out of step with the server.
We caught two bugs along the way. On iOS, a write made while another was waiting to retry got no answer, so the sheet's save button stayed stuck. On the web, a single dropped request put the whole app in offline mode and held every write until the next board fetch. Now any response from the server counts as connected.
We measured iOS again the same way. When two different tasks are checked in a row, the second write now leaves at 1.33 s instead of 4.16 s. Together with a fix that batches refetches, the requests during five checks fell from 35 to 20.
What people see
The queue works quietly, but it doesn't hide.
- While writes are waiting, a "3 changes to send" bar appears. While sending, it reads "Sending · 3 changes".
- A row touched by an unsent write gets a small cloud mark at its end.
- Text captured offline stays as "Will read when connected", then finds its place after reconnecting.
- Writes that waited over a day ask "3 changes waited over a day · Send them?" with Send and Discard.
- Writes that couldn't be sent are listed with a reason: deleted or not visible (404), can't be edited (403), changed elsewhere (409), or clashed with another item (id conflict).
- Signing out with writes still waiting tells you how many will be lost first.
What we learned
Accepting writes offline came down to asking, for every write, whether it's safe to send again. Sometimes a write that looks unsafe becomes safe once you change its shape. Creates became safe with no new table and no header, just by letting the app pick the id.
The bigger lesson was that a mechanism built for being offline can make being online slower. The one-line queue was right if you only looked at offline, and the problem showed up only when we measured online. The fix changed the rule in one place, the policy, and both apps checked the change against the same scenarios.