[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"nav-notes-count":3,"content-note-what-i-learned-building-a-local-first-sync-engine":4},9,{"id":5,"title":6,"author":7,"authorAvatar":8,"authorRole":9,"body":10,"category":246,"date":247,"description":234,"excerpt":248,"extension":249,"image":250,"index":251,"meta":252,"navigation":265,"path":266,"pullQuote":267,"readingTime":268,"seo":269,"slug":270,"stem":271,"takeaways":272,"total":276,"__hash__":277},"notes\u002Fnotes\u002Fwhat-i-learned-building-a-local-first-sync-engine.md","What I Learned Building a Local-First Sync Engine","Norbert Brett","\u002Fimages\u002Fnorbert-brett.jpg","Full-Stack & AI Systems Engineer",{"type":11,"value":12,"toc":233},"minimark",[13,18,22,30,85,92,96,99,108,119,135,139,142,160,184,187,191,194,215,219],[14,15,17],"h2",{"id":16},"what-breaks-when-every-click-waits-on-the-network","What Breaks When Every Click Waits on the Network",[19,20,21],"p",{},"Before I wrote production TypeScript or Go, I spent eleven years working in commercial transit and logistics across Birmingham and Budapest. If you have ever stood inside a reinforced-concrete bus depot at 5:30 AM watching drivers log pre-departure safety checks on a tablet, you know how fragile traditional web applications really are. A tablet drops from 4G to zero bars right as the driver submits a brake-fault report. The loading spinner turns for twenty seconds, the browser tab times out, and the worker—who felt exhausted before the shift even started—refreshes the page and loses the entire inspection form.",[19,23,24,25,29],{},"When I built the ",[26,27,28],"strong",{},"Local-First Sync Engine"," in 2025, my goal was simple: make a web application behave like a reliable physical notebook when offline, and like a real-time cloud system when online.",[31,32,33,38],"blockquote",{},[19,34,35],{},[26,36,37],{},"In Plain English — How \"Local-First\" Software Works:",[39,40,41,53],"ul",{},[42,43,44,47,48,52],"li",{},[26,45,46],{},"Traditional Cloud Web App",": Every time you click \"Save,\" your browser has to send a message across the internet to a distant server and wait (",[49,50,51],"code",{},"150–400ms",") for confirmation. If your Wi-Fi or mobile signal blinks, you get a spinning wheel or an error.",[42,54,55,66,67,73,74,77,78,80,81,84],{},[26,56,57,58,61,62,65],{},"Local-First Web App (",[49,59,60],{},"SQLite WASM"," + ",[49,63,64],{},"IndexedDB",")",": We place a miniature, industrial-strength database right inside your browser tab. ",[26,68,69,70,65],{},"WebAssembly (",[49,71,72],{},"WASM"," lets us run the rock-solid ",[26,75,76],{},"SQLite"," database engine at near-native speed inside Chrome or Safari, while ",[26,79,64],{}," stores the data safely on your device's disk. Every click saves locally in under ",[26,82,83],{},"2 milliseconds","—even in airplane mode—and a quiet background worker syncs with the central server whenever signal returns.",[19,86,87],{},[88,89],"img",{"alt":90,"src":91},"Local-First Sync Architecture Diagram","\u002Fimages\u002Fnotes\u002Fdiagrams\u002Fwhat-i-learned-building-a-local-first-sync-engine.svg",[14,93,95],{"id":94},"four-failure-modes-that-only-show-up-after-you-go-offline","Four Failure Modes That Only Show Up After You Go Offline",[19,97,98],{},"Building a demo that saves data locally takes a weekend; surviving real 12-hour field shifts takes careful engineering around four failure cases. Months earlier, during my first stress test simulating two dispatch tablets offline for a full shift, I was annoyed to watch three naive assumptions fail back-to-back.",[100,101,103,104,107],"h3",{"id":102},"_1-device-clocks-lie-datenow-cannot-be-trusted","1. Device Clocks Lie (",[49,105,106],{},"Date.now()"," Cannot Be Trusted)",[19,109,110,111,113,114,118],{},"When two offline workers edit the same record and reconnect later, how does the server know which edit happened second? My earliest prototype simply checked the tablet's built-in wall clock (",[49,112,106],{},"), a rule called ",[115,116,117],"em",{},"Last-Write-Wins",". That broke immediately when one test tablet had its system clock running four minutes fast: every edit from that fast tablet silently overwrote newer work from everyone else.",[31,120,121],{},[19,122,123,126,127,130,131,134],{},[26,124,125],{},"In Plain English — What is a \"Hybrid Logical Clock\" (HLC)?","\nInstead of trusting a device's wall clock alone, an ",[26,128,129],{},"HLC"," stamps every edit with three pieces of information: ",[49,132,133],{},"(Physical Time + Step Counter + Device ID)",". Even if a tablet's clock is slightly off, the step counter ticks upward whenever devices exchange messages, guaranteeing a fair, unbroken timeline of cause and effect.",[100,136,138],{"id":137},"_2-safe-field-merges-vs-business-rules-who-gets-the-last-spare-van","2. Safe Field Merges vs. Business Rules (\"Who Gets the Last Spare Van?\")",[19,140,141],{},"Not all offline conflicts are equal, and treating them the same way causes real operational bugs:",[39,143,144,150],{},[42,145,146,149],{},[26,147,148],{},"Safe Parallel Edits (Column-Level Merge)",": If Dispatcher A updates a vehicle's parking bay while Mechanic B updates the mileage on the same vehicle while offline, both changes touch different fields. The sync engine merges both automatically.",[42,151,152,155,156,159],{},[26,153,154],{},"Exclusive Resource Conflicts (Idempotent Server Mutators)",": What if two dispatchers, both offline, assign the ",[115,157,158],{},"same"," spare van to two different routes? You cannot merge half a van.",[31,161,162],{},[19,163,164,167,168,171,172,175,176,179,180,183],{},[26,165,166],{},"In Plain English — What is an \"Idempotent Mutator\"?","\nA ",[26,169,170],{},"Mutator"," is a named business command (like ",[49,173,174],{},"\"Assign Van #14 to Route B\"",") rather than a raw spreadsheet cell edit. ",[26,177,178],{},"Idempotent"," means that if a spotty mobile connection sends that same command three times in a row, the server executes it ",[115,181,182],{},"once"," and never creates three duplicate bookings.",[19,185,186],{},"When the tablets reconnect, our Python FastAPI and PostgreSQL server replays those commands in strict order. The first route assignment succeeds; the second tablet receives an instant notification flagging the conflict in a \"Needs Review\" tray so a human dispatcher can pick another vehicle—zero silent overwrites.",[100,188,190],{"id":189},"_3-preventing-browser-storage-eviction-and-two-tab-collisions","3. Preventing Browser Storage Eviction and Two-Tab Collisions",[19,192,193],{},"Mobile browsers sometimes clean up website storage if a device runs low on disk space. Early on, I felt relieved when we caught an iOS Safari storage-clearing edge case during lab testing before any real shift logs lived in it. We solved it with two browser standards:",[195,196,197,204],"ol",{},[42,198,199,200,203],{},"Calling ",[49,201,202],{},"navigator.storage.persist()"," at login so the browser marks the database as protected operational data.",[42,205,206,207,210,211,214],{},"Using the ",[26,208,209],{},"Web Locks API"," (",[49,212,213],{},"navigator.locks.request",") so if an operator opens two tabs of the app at once, they take turns writing cleanly instead of corrupting the local file.",[100,216,218],{"id":217},"_4-reconnecting-after-12-hours-with-4000-queued-edits","4. Reconnecting After 12 Hours With 4,000 Queued Edits",[19,220,221,222,225,226,229,230,232],{},"If a field tablet records 4,000 status updates during a 12-hour shift and tries to fire 4,000 separate internet requests the second Wi-Fi reconnects, it freezes the browser. Instead, our background sync worker ",[26,223,224],{},"compacts the history"," (if a status changed five times offline, it folds them into a single net update) and streams compressed batches of 250 items at a time. In our benchmark workload, this local-first delta sync reduced central PostgreSQL server read load by ",[26,227,228],{},"74%"," while keeping every button click inside the app under ",[26,231,83],{},".",{"title":234,"searchDepth":235,"depth":235,"links":236},"",2,[237,238],{"id":16,"depth":235,"text":17},{"id":94,"depth":235,"text":95,"children":239},[240,243,244,245],{"id":102,"depth":241,"text":242},3,"1. Device Clocks Lie (Date.now() Cannot Be Trusted)",{"id":137,"depth":241,"text":138},{"id":189,"depth":241,"text":190},{"id":217,"depth":241,"text":218},"Design Systems","November 7, 2026",null,"md","\u002Fimages\u002Fnotes\u002Fwhat-i-learned-building-a-local-first-sync-engine.webp","02",{"sections":253},[254,259],{"marker":255,"heading":17,"body":256},"\u002F A",[257,258],"Before moving into full-stack engineering, I spent eleven years in commercial transit and logistics operations in the UK and Hungary. If you have ever watched a dispatcher or driver try to submit a vehicle inspection checklist in a depot dead zone, you have seen what happens when a traditional web app blocks on a 300ms POST request: spinners hang, workers tap Submit three times, and shift records vanish.","In 2025, I built the Local-First Sync Engine so that every read and write hits a browser-resident SQLite-over-WASM and IndexedDB store in under 2 milliseconds. The UI never waits on cellular coverage.",{"marker":260,"heading":261,"body":262},"\u002F B","Conflict Resolution, Clock Drift, and Schema Migration Traps",[263,264],"Moving the primary database into the client tab solves latency immediately, but it shifts the complexity into synchronization. Standard wall-clock timestamps fail the moment a field tablet's system clock drifts by four minutes.","Replacing raw Date.now() Last-Write-Wins with Hybrid Logical Clocks (HLC) and routing multi-user inventory reservations through idempotent server mutators eliminated lost field mutations while cutting backend PostgreSQL read load by 74%.",true,"\u002Fnotes\u002Fwhat-i-learned-building-a-local-first-sync-engine","A lost cellular connection inside a reinforced-concrete transit depot should never be the web equivalent of an application crash.","8 min read",{"title":6,"description":234},"what-i-learned-building-a-local-first-sync-engine","notes\u002Fwhat-i-learned-building-a-local-first-sync-engine",[273,274,275],"Local-first apps save data inside the device browser first (\u003C2ms), eliminating loading spinners and lost forms when Wi-Fi or 4G drops.","Device clocks drift: use Hybrid Logical Clocks (HLC) instead of basic wall-clock timestamps so offline edits never overwrite newer work.","Batching and compacting offline edits before syncing cuts backend PostgreSQL database read load by 74%.","10","mxgJrFBZ1hpm5i7g_pMpNJDOdxsq67fw_F_la7_3F-w"]