Offline Sync Without Duplicate Bills: Flutter, ASP.NET Core and UUID v5
Office PCs and salesmen's phones, one server, and an internet connection that comes and goes. Here's how MRF Sales keeps them in sync without ever creating the same bill twice.
MRF Sales is the billing, stock and ledger system I built for a printer-consumables wholesaler in Chattogram. It started as a Flutter desktop app on one office PC with a local SQLite database. Then the owner asked for the obvious next thing: the other office PCs and the salesmen's phones should all see the same bills, payments and stock — and billing must not stop when the internet does, because in Chattogram it often does.
That's an offline-sync problem, and for a billing system the stakes are specific. A sync bug in a notes app gives you a duplicated note. In a ledger it gives you a duplicated bill, a customer charged twice, and an owner who stops trusting the software. So the design was driven by one question: what has to be true so that no matter how the network behaves, every bill exists exactly once?
Every save goes to the device first
Each PC and phone keeps its own full SQLite copy and saves there first, with the same business rules it would apply online. In the same transaction, the change is also written to an outbox table as one operation — bill.create, payment.receive, stock.in and so on:
CREATE TABLE sync_outbox (
seq INTEGER PRIMARY KEY AUTOINCREMENT,
op_id TEXT NOT NULL UNIQUE, -- a UUID made on the device
type TEXT NOT NULL, -- bill.create, payment.receive, ...
payload TEXT NOT NULL, -- JSON
user_id TEXT,
created_at TEXT NOT NULL, -- UTC on this device
op_date TEXT NOT NULL, -- the business date on this device
status TEXT NOT NULL DEFAULT 'pending',
message TEXT,
tries INTEGER NOT NULL DEFAULT 0
);
The UI never waits on the network. A salesman standing at a shop counter gets his bill printed whether or not there's a signal; the outbox is a background concern.
Apply each change exactly once
The device pushes its outbox to the ASP.NET Core API in order, as { deviceId, ops: [...] }. The server records every operation id it has seen. If an id comes back a second time — because the phone lost signal after the server saved the bill but before the response arrived — the server doesn't apply it again. It returns the answer it gave the first time:
var done = await db.SyncOps.AsNoTracking()
.FirstOrDefaultAsync(o => o.Id == op.OpId);
if (done is not null)
return new PushResult(op.OpId, done.Status, done.Message, 0);
Order matters too. If an operation fails because of a server problem (not a rule), the push stops there and the rest wait for the next try. A payment is never applied before the bill it pays.
The same ids on every device
This is the part that made everything else simple. A bill isn't one row — it's an invoice, its lines, stock moves, a ledger entry, maybe a discount entry. If the device and the server each generated their own random ids for those rows, every sync would have to map "my id" to "your id" forever.
Instead, every row an operation creates gets a UUID v5 derived from the operation id and the row's role: uuidV5(opId, "invoice"), uuidV5(opId, "item:0"), uuidV5(opId, "ledger:discount"). The device computes them when it saves offline; the server computes the same ones when it applies the change. Same input, same id, on both sides:
/// Id for a row this change creates. Offline: the same id the device
/// gave it (UUID v5 of the change id and the role). Online: random.
public string NewId(string role) =>
OpId is null ? Guid.NewGuid().ToString() : Ids.V5(OpId, role);
It also gives a second safety net for "saved, but the answer was lost". If applying an operation hits a unique-key error, the server checks whether the invoice with id uuidV5(opId, "invoice") already exists. If it does, the change was already applied, and the device is simply told so.
Watch out: .NET's Guid stores its first three fields little-endian, while the UUID standard is big-endian. A hand-rolled v5 in C# has to swap byte order before and after hashing, or it won't match the Dart uuid package — and every synced row gets a different id on each side.
Bill numbers that can't collide
Ids are invisible; bill numbers aren't. Customers see them, and two salesmen billing offline at the same moment must not both print bill 20250417. So each device holds a reserved block of numbers: 50 bill numbers and 50 receipt numbers, and smaller blocks for returns and purchases. Offline work is numbered from the device's own block. Online numbers skip every reserved block. When a device has used half of a block, it asks for the next one the next time it's online.
Accept, then flag
Here's the decision that took the longest, and it was a business decision, not a technical one. Online, the server refuses a bill that oversells stock or pushes a salesman over his credit limit. But what about a bill made offline that breaks a rule? The goods have already left the shop. Refusing it on the server doesn't undo the sale — it just loses the record of it.
So, agreed with the owner: offline rule breaks are saved and flagged. The same rule check throws online and records a problem offline:
/// Online: refuse with [message]. Offline: save anyway and add a
/// Sync problem for the admin.
public void Break(string kind, string message, ...)
{
if (!Offline) throw new RuleViolation(message);
Flag(kind, message, entity, entityId);
}
The admin gets a Sync problems list: overselling, over-limit bills, prices below the base price, a reused bank reference, a duplicate party. Permission breaks are different — a staff member who wasn't allowed to give a discount can't gain that power by going offline — so those are refused, and listed too.
Dates get the same treatment. An offline bill keeps the day it was made on the device. A future date (a phone clock set wrong) becomes today, and anything older than seven days is saved but flagged, because "offline for two weeks" is worth a question.
Instant updates, without polling to death
Pushing is half of sync; the other half is every other screen finding out. Devices keep a SignalR connection to the server. After each successful write, the server sends a single changed signal — at most one per 300 ms burst — and each device runs its normal pull, asking only for rows changed since its last sync. Other screens update in under a second. If the socket is down, the app falls back to checking every 20 seconds.
The first sync of the full real dataset — 18 years of history, about 248,000 rows — takes around 8 seconds.
What carries over to any offline-first app
- Save locally and queue an operation, not a diff of rows. Operations can be replayed, ordered and deduplicated.
- Give each operation an id made on the device, and have the server remember which ids it has applied. That's what makes retries safe.
- Derive row ids from the operation id (UUID v5) so both sides agree without a mapping table.
- Anything a human reads, like bill numbers, needs its own collision plan. Reserved blocks per device are simple and work.
- Decide with the business what happens to offline work that breaks a rule. Usually it's "keep it and tell someone", not "throw it away".