Forem: Max Friedmann

Works Offline, Syncs Automatically: How smallstack Implements Local-First Architecture

Max Friedmann — Mon, 13 Apr 2026 12:07:17 +0000

Most web apps are optimized for the happy path: fast internet, reliable servers, users sitting at their desks. But the real world looks different. Field technicians in basements. Property managers in underground parking garages. Service workers on remote sites. For these users, "your connection was lost — please try again" is not an acceptable error message.

This is why we built smallstack on a local-first architecture. Here's what that actually means in practice.

Local-First vs. "Offline Mode"

"Offline mode" is what most apps call it when they let you view cached content without an internet connection. You can browse — but the moment you try to save something, you hit a wall.

Local-first is different in a fundamental way: the local device is the primary storage location. The app reads from and writes to local storage first. The server is a sync partner, not the single source of truth.

The practical difference:

Offline mode: read-only without connection
Local-first: full read/write without connection, automatic sync when reconnected

How Incremental Sync Works

The challenge with local-first isn't the offline part — that's straightforward. The hard part is sync: how do you reconcile changes made by multiple users who were offline at the same time?

smallstack uses SignalDB for incremental sync. The key design decision: instead of syncing entire collections, we sync only the deltas — changes since the last known sync point. Each change carries a timestamp. On reconnect, the sync protocol exchanges only what changed since the last successful sync.

This approach has several practical advantages:

Minimal bandwidth — particularly important for users on mobile connections
Fast reconnect — syncing 50 changed records is much faster than re-downloading thousands
Real-time propagation — changes from one user appear at other clients within seconds of reconnecting

Conflict Resolution

When two users edit the same field while offline, you have a conflict. Our approach for most cases is last-write-wins with timestamp ordering. The most recent change (by device clock) wins.

This covers the majority of real-world cases. For more complex scenarios — like numeric counters that both users incremented — the data model can define merge strategies. The goal is predictable behavior that teams can reason about, not invisible magic.

A Real Scenario: Field Service Inspection

Here's a concrete example of how this plays out:

A service technician arrives at an industrial site with no mobile coverage. They open the smallstack PWA (installed from browser — no app store needed). The app loads with all their assigned tasks already cached from the last sync.

They complete three inspections, attach photos, add notes. All changes are written to local IndexedDB immediately — no spinners, no "saving..." indicators. The UI is instant.

An hour later, back in the parking lot with signal, the app reconnects. SignalDB runs the incremental sync: the three new inspection records and their attached file references are pushed to the server. Within seconds, the office team can see the completed inspections on their dashboard.

No manual "sync now" button. No lost data. No double-entry.

Why This Architecture Matters for Business Apps

For consumer apps, offline support is a nice-to-have. For business-critical workflows, it's different: if your team can't record data, they either lose it or work around your tools. Both outcomes are bad.

Local-first removes this failure mode entirely. The app works regardless of connection state. This makes it genuinely suitable for:

Field service teams working in buildings with poor coverage
Trades and construction where sites often have no reliable WiFi
Property management — inspections, maintenance logs, tenant records
Any team that needs reliability over SaaS uptime dependence

The Performance Bonus

Offline capability is the headline, but local-first has a performance side effect that benefits everyone — including users who are always online.

When data lives locally, read operations are instant. Filtering a list of 5,000 records? No network round-trip. The UI is as fast as the local machine, not as fast as the network.

This changes how you can design UIs. You can afford live filtering, real-time search, and reactive dashboards without debouncing every keystroke or showing skeleton loaders everywhere.

Try It Yourself

smallstack ships this local-first architecture as part of its no-code platform — you get offline capability and real-time sync without writing a line of sync code yourself. The widget-based app builder sits on top of this foundation.

If you want to dig deeper into the technical side, check out the smallstack documentation or try building a simple app on the free tier to see the sync behavior in action on smallstack.com

Building something local-first? Have questions about the sync approach? Drop a comment — happy to get into the details.

CRDTs and Local-First Architecture: How smallstack Handles Offline Conflict Resolution

Max Friedmann — Wed, 08 Apr 2026 20:30:16 +0000

CRDTs and Local-First Architecture: How smallstack Handles Offline Conflict Resolution

Most web apps treat the network as a prerequisite. No connection? You get a spinner, an error banner, or worse — silent data loss. At smallstack, we made a different choice from the start: local-first.

This post breaks down what that means technically, how we use CRDTs and SignalDB to handle conflict resolution, and why this architecture matters for building serious business software.

The Problem with "Offline Mode"

"Offline mode" is a spectrum. At the bad end: you cache the last-loaded page and show a banner saying "you're offline, changes won't be saved." At the slightly better end: you queue writes locally and flush them when connectivity returns — but without any conflict handling, so the last writer wins (silently destroying the other's work).

Neither is good enough for field teams who genuinely work disconnected for hours at a time.

Local-first inverts the model:

The local device is the primary data store, not a cache.
Reads are instant — no network roundtrip.
Writes are committed locally first, then synced.
The server's job is replication between peers, not the source of truth.

This changes the UX fundamentally: no loading spinners, no "connection lost" interruptions, no perceived latency. But it requires solving a hard problem — what happens when two users modify the same record while offline?

Enter CRDTs

CRDT stands for Conflict-free Replicated Data Type. A CRDT is a data structure where concurrent modifications from multiple sources can always be merged into a consistent result without coordination — no locks, no conflict resolution UI, no data loss.

The key insight: instead of storing "the current value," CRDTs store operations or state vectors that can be merged in any order and always produce the same result (a property called commutativity and associativity).

A practical example

Two field technicians, Anna and Ben, are offline:

Anna updates the status of Work Order #42 to in_progress.
Ben adds a note to Work Order #42: "Need replacement part."

When both sync:

Two independent operations on the same record.
Both changes are present in the merged result.
No conflict.

What if both update the same field — say, the status field?

smallstack uses Last-Write-Wins (LWW) semantics for scalar fields, with a logical timestamp (not wall clock). The operation with the higher timestamp wins. For collaborative text editing or list structures, LWW doesn't cut it — and that's where proper CRDT types (like Logoot or RGA for sequences) come in.

SignalDB: Incremental Sync in Practice

smallstack uses SignalDB — a reactive, local-first database for the browser built with TypeScript. It's the layer between our SvelteKit frontend and the MongoDB backend.

The sync protocol works like this:

Client → Server: "Give me everything updated after timestamp T"
Server → Client: [delta of changed documents]
Client:          Merge deltas into local collection
                 Notify reactive subscribers ($state runes update automatically)

Every document in SignalDB has an updatedAt field. On reconnect, the client sends its latest known timestamp, and the server returns only what's changed since then — not the full dataset. This makes initial sync fast and incremental updates tiny.

// Simplified example of how sync works under the hood
collection.sync({
  pull: async (lastPulledAt) => {
    const changes = await fetch(`/api/orders?updatedAfter=${lastPulledAt}`);
    return changes.json(); // Only the delta
  },
  push: async (changes) => {
    await fetch('/api/orders', {
      method: 'POST',
      body: JSON.stringify(changes)
    });
  }
});

Svelte 5 runes make this reactive binding seamless:

// In a .svelte.ts service file
class OrderService {
  orders = $state<Order[]>([]);

  constructor() {
    // SignalDB collection drives $state reactively
    collection.find().onChange((result) => {
      this.orders = result;
    });
  }
}

Every time the sync delivers new data, orders updates automatically, and all components using it re-render. No manual refresh, no writable() stores — just reactive local state that happens to be backed by a synced collection.

Real-Time on Top of Local-First

Local-first doesn't mean "eventually consistent and slow." smallstack also supports real-time push from the server using server-sent events. When a user makes a change:

It's committed locally (instant, no network wait).
It's pushed to the server asynchronously.
The server broadcasts the change to other connected clients.
Those clients merge the incoming delta into their local store.
Their reactive state updates.

From the perspective of a connected user, it feels like Google Docs — changes appear immediately. From the perspective of a disconnected user, nothing breaks — changes queue locally and sync when reconnected.

What This Means for the Architecture

Building local-first requires discipline:

No server-side rendering for user data. If data lives in the client's SignalDB, SSR can't hydrate it. We SSR only public, non-personalized content. Authenticated app views are entirely client-rendered.

Schema must travel with data. When a user defines a custom data type in smallstack (our no-code type system), that schema has to be available locally for validation and rendering — even offline.

Migrations are tricky. If the server schema changes and a client is offline, we need to handle schema version mismatches gracefully on sync. We version migrations and apply them lazily on the client.

Conflict policy must be explicit. For every field type, we define the merge strategy upfront: LWW for most scalar fields, custom merge for structured types like address objects, append-only for logs and history.

Why Most No-Code Platforms Can't Do This

Building local-first isn't a feature you can add later. It requires rethinking the data flow from day one:

Central-server tools (Airtable, Monday, Notion) make the server the source of truth. Offline is an afterthought — literally bolted on after the fact.
Adding CRDT-based sync to an existing server-centric codebase means rebuilding the entire persistence and sync layer.

We made the local-first decision before writing the first line of product code. That's why it actually works — on construction sites, in basements, on planes, in tunnels.

Try It

If you're building business software that needs to work in environments with unreliable connectivity, the local-first approach is worth the investment. SignalDB is open source and well-documented — a good starting point.

smallstack is the no-code platform built on this foundation. If you want to see what it looks like to give non-technical users a reliable, offline-capable business app — check out the docs or try the free tier.

Questions about the architecture? Drop them in the comments — happy to go deeper on any part of this.

I built a CLI to see my real GitHub language stats – does something like this already exist?

Max Friedmann — Sun, 22 Feb 2026 19:03:19 +0000

I recently created my new online CV and wanted to show all of my contributions — also the ones from private repositories. My GitHub profile looked nearly empty, even though I'd been coding professionally for years. Most of that work just happened to live in private repos.

Example of how the output data can be visualized — this chart is from my CV app, built on top of the JSON data this tool produces

That's when I realized: GitHub's profile is basically useless for showing your real activity as a professional developer. So I started looking for a tool that could compute honest, per-language stats from all my commits — public and private. I couldn't find one. So I built it: github-lang-stats.

What it does

It scans every commit you've personally authored on GitHub — including private repos — and calculates how many lines you've changed per programming language. The result is an honest, verifiable snapshot of your actual work.

npx github-lang-stats --token=<your-github-pat>

That's it. No install needed. Just a GitHub Personal Access Token.

Why not just use the GitHub profile?

No language breakdown — GitHub shows total contributions, not which languages you used
Private repos are invisible — Most (of my) professional work happens in private repos, which don't show up at all

Try it out!

👉 github-lang-stats on npm

I'd love to hear your thoughts:

Did you know of a similar tool? (I couldn't find one!)
Would you use this for your portfolio or resume?
What features would you want to see?

Drop a comment below — all feedback, issues, and PRs are welcome on GitHub! ⭐