Decision: draft debounce interval #4

New issue

Closed

opened 2026-07-23 14:46:22 +02:00 by cloudbot · 1 comment

cloudbot commented

2026-07-23 14:46:22 +02:00

Collaborator

Decision #4 — pick the draft-autosave debounce interval and the background-sync frequency cap.

While a user edits an entry, changes are batched and pushed to Outline on an idle debounce (a single editMode: replace per tick). The prototype surfaces this to the user only as "Draft autosaves every few seconds"; it doesn't commit to a number.

The trade-off

Shorter interval (e.g. 2s) → less data lost if the app dies mid-edit, but more Outline API traffic and more revision-check churn during active typing.
Longer interval (e.g. 5–8s) → fewer API calls, but a larger window of unsaved work.

Two values to set:

Idle debounce — how long after the last keystroke before a tick fires (proposed 3–5s idle).
Background-sync frequency cap — a floor on how often ticks may actually hit the API, so fast typing can't hammer Outline.

What to decide

The concrete debounce value (or a small range) and the minimum inter-sync gap for the cap.

Blocks: the sync engine's debounce/WorkManager scheduling.

Recommendation: 4s idle debounce with a hard cap of one sync per 4s while a sheet is open. It sits in the middle of the proposed range, keeps "autosaves every few seconds" honest, and the cap prevents runaway calls. Publish always forces an immediate final tick regardless of the cap.

Source: Solution Design — Family App v1 §7 (doc vpBNbG4TsV), decision §13 #4.

**Decision #4 — pick the draft-autosave debounce interval and the background-sync frequency cap.** While a user edits an entry, changes are batched and pushed to Outline on an idle debounce (a single `editMode: replace` per tick). The prototype surfaces this to the user only as "Draft autosaves every few seconds"; it doesn't commit to a number. ### The trade-off - **Shorter interval** (e.g. 2s) → less data lost if the app dies mid-edit, but more Outline API traffic and more revision-check churn during active typing. - **Longer interval** (e.g. 5–8s) → fewer API calls, but a larger window of unsaved work. Two values to set: 1. **Idle debounce** — how long after the last keystroke before a tick fires (proposed **3–5s idle**). 2. **Background-sync frequency cap** — a floor on how often ticks may actually hit the API, so fast typing can't hammer Outline. ### What to decide The concrete debounce value (or a small range) and the minimum inter-sync gap for the cap. **Blocks:** the sync engine's debounce/WorkManager scheduling. **Recommendation:** **4s idle debounce with a hard cap of one sync per 4s** while a sheet is open. It sits in the middle of the proposed range, keeps "autosaves every few seconds" honest, and the cap prevents runaway calls. Publish always forces an immediate final tick regardless of the cap. **Source:** Solution Design — Family App v1 §7 ([doc vpBNbG4TsV](https://outline.marquezkeenan.family/doc/solution-design-family-app-v1-vpBNbG4TsV)), decision §13 #4.

cloudbot added this to the M0 · Open Questions & Decisions milestone

2026-07-23 14:46:22 +02:00

cloudbot added the

spike

label

2026-07-23 14:46:22 +02:00

cloudbot added a new dependency

2026-07-23 14:46:43 +02:00

#26 Create-once-then-replace sync engine + conflict detection

cloudbot added a new dependency

2026-07-23 14:46:47 +02:00

#35 Draft autosave debounce → sync