Chapter 1
The system we were actually building
The difficult part was not building individual modules. It was deciding what guarantees the overall system could make when those modules interacted under imperfect conditions.
Sync connects orders, tables, Host Stand, reservations, kitchen routing, delivery, menu and pricing, customer records, reporting, and staff permissions. Each area has its own interface, but none of them is operationally independent. Seating a table changes the context for an order. A sales channel changes pricing. A delivery address can become a dependency of a transaction. A role determines whether an action is permitted at all.
The operating environment adds more constraints. A workspace may switch between Arabic and English, right-to-left and left-to-right layouts, SYP and USD, several employee roles, different device types, degraded connectivity, restaurant-operated delivery, and multiple restaurants under one account.
This changes the product question. Instead of asking only whether a feature works, we have to ask what it knows, which state it is allowed to change, whether that state is current, and what should happen if confirmation becomes impossible halfway through the operation.
Chapter 2 · Case I
Offline is easy until money is involved
Reading cached data is one problem. Completing a transaction whose authoritative price cannot currently be confirmed is a different one.
The scenario
A restaurant loses connectivity while an employee is taking an order. Keeping the menu visible is relatively straightforward because the device can use previously loaded data. Now suppose the cashier builds an order and receives 180,000 SYP in cash while the connection is unavailable.
The device cannot ask the server to confirm the final authoritative price. During the outage, a product price may change, a discount may expire, a tax rule may change, an addition may become invalid, a delivery fee may differ, or another server-side business rule may produce a different result.
Operational continuity
The restaurant should not become unusable whenever connectivity drops.
Transactional integrity
The client should not present locally calculated pricing as authoritative when the server has not confirmed it.
Alternatives considered
Trust the client
The device calculates the transaction locally and submits the result later.
Advantage: maximum offline availability.
Problem: the client may create a transaction that the authoritative system would never have approved.
Disable checkout offline
Cached information remains readable, but order creation is blocked until connectivity returns.
Advantage: strong consistency.
Problem: a connectivity failure can stop a core restaurant operation.
Controlled offline transaction
Allow a deliberately narrow cash workflow, preserve pricing authority where possible, and expose uncertainty where it is not.
Advantage: continuity without pretending the client is the source of truth.
Cost: more state, stricter role boundaries, and occasional manual review.
What offline does and does not mean
Devices do not synchronize directly with one another while offline. Each supported device can continue using its available offline workflows independently. When connectivity returns, queued operations are reconciled against authoritative server state. If conflicting operations occurred on separate devices, the conflict remains visible and an authorized manager can resolve it.
The restaurant as a whole does not stay synchronized during an internet outage. Each device keeps working on its own, and the server decides what is accepted afterwards.
Server-side price snapshots
While connected, the device asks the server for a pricing snapshot. POST /orders/pricing-snapshots runs the same pricing engine as normal order creation and saves the full pricing result together with a binding that describes the exact order inputs: restaurant, items, add-ons, address, table, coupon, discount, sales channel, taxes, and the full pricing breakdown.
The client receives only a snapshot ID, a version, and a SHA-256 hash. The hash is not a signature, and it is not what makes the snapshot authoritative. The server keeps the original snapshot, so a client cannot create its own valid price lock.
If the order is saved during an outage while its snapshot is still valid, the queued order references that snapshot. Changing a price-affecting input—items, quantity, add-ons, order type, delivery address, table, coupon, discount, or sales channel—breaks the binding. When synchronization occurs, the server checks that:
- the snapshot exists and belongs to the restaurant;
- it was issued to the same cashier;
- the version and hash match;
- the stored payload is intact;
- it has not expired on the server;
- the order inputs match the original binding;
- the restaurant, products, and add-ons are still operationally valid.
If every check passes, the server creates the order using the locked server-side prices. The client’s frozenPricing values are never used as authoritative order totals; they are kept only for audit and Sync Center visibility. Retries reuse the same identity and idempotency behavior, so a lost response does not create multiple snapshots or orders.
The current beta configuration retains pricing snapshots and treats them as valid for 90 days through OFFLINE_PRICING_SNAPSHOT_RETENTION_DAYS. It is a configurable setting, not a fixed product or business rule.
When there is no valid lock
The device may still have enough cached information to display an estimated total. That estimate can help the employee record what happened, but it cannot be treated as an approved price. The interface explicitly labels the distinction before saving the cash entry locally.
Cached does not mean confirmed.
An estimate-only entry is never sent directly to the ordinary order-creation path. After reconnection, it remains in Sync Center under manager review.
When a snapshot expires
Expiry can happen at two different points, and the two cases recover differently.
The snapshot expires before the order is created offline. The device removes the expired snapshot and switches the order to ESTIMATE_ONLY, and the order is queued with an estimated total. Once the device is online, a manager can use Lock price & submit: the server creates a fresh pricing snapshot at current prices, and the action is rejected if the cash collected is lower than the fresh total. The same durable IDs are reused, so the order is not duplicated.
The order was queued with a valid snapshot, but the snapshot expires before synchronization. The server returns PRICING_SNAPSHOT_EXPIRED and the submission moves to NEEDS_MANAGER_REVIEW. In the current implementation, the manager can only reject this submission. A recovery path that reprices it is not built yet.
An estimate is not silently promoted into an authoritative transaction.
Chapter 3 · Case II
The request can fail even when the operation succeeds
A lost response creates a different kind of uncertainty: the client does not know whether it is safe to try again.
The ambiguous outcome
The device sends a Create Order request. The server successfully creates the order, but the network drops before the response reaches the device. From the device's point of view, the request appears unsuccessful. The system now has to distinguish between an operation failure and a response failure.
If the application retries by creating a brand-new order, it may produce a duplicate. A retry must instead represent the same intended operation.
Replay also has dependencies
Queue recovery is not simply “send everything again.” A new delivery address may need to synchronize before the order that references it. A temporary Host Stand identity may need to be remapped before a later action can be replayed. Actions for another restaurant under the same account may need to wait until that restaurant is selected.
The queue therefore preserves identity, ordering, restaurant scope, and partial dependency progress. Transport failures, authentication failures, business-rule failures, and inventory conflicts also remain distinguishable because they require different recovery behavior.
Visible recovery
Restored internet access does not mean every operation has synchronized. Queued operations can be waiting, retrying, completed, failed, blocked, conflicted, or awaiting review. Failed and conflicted entries remain visible so staff can resolve them.
Reliability is not only preventing failure. It is making failure understandable.
Weak connection is not the same as offline
A device may report internet connectivity while the backend path is slow, unstable, intermittently unreachable, or recovering. Treating that state as simply online can cause repeated loaders, duplicate refreshes, and unnecessary retries.
On a degraded path, Sync keeps cached content visible, reduces background work, coalesces duplicate refreshes, and prioritizes the active operational surface. Recovery requires confirmed backend reachability rather than a change in the device's connectivity icon alone.
Chapter 4 · Case III
Shared state does not require a shared interface
The owner, floor manager, cashier, waiter, receptionist, kitchen operator, and driver work with the same restaurant state, but they do not need the same abstraction over it.
Roles
The product decision was to keep shared data underneath role-specific operational surfaces. A host needs table capacity, arrival state, and active sessions. A cashier needs order and payment decisions. A driver needs assigned work and delivery progress. An owner needs broader control and inspection.
Permissions are therefore more than navigation restrictions. They determine which actions are safe. Offline cash orders, for example, are deliberately limited to owners, floor managers, and cashiers; a waiter, receptionist, kitchen account, or delivery account cannot enter the same queue flow.
Permission design is part of workflow design.
Arabic and right-to-left operations
The same workflow may appear in English left-to-right or Arabic right-to-left. Localization changes more than labels: it affects navigation, reading order, typography, form alignment, currency presentation, mixed-direction content, action placement, and printed output.
Platforms change the environment
Sync runs across mobile, PWA, and desktop environments, but the same capability does not imply the same interaction conditions. Installation, lifecycle, notification behavior, update delivery, storage, background work, and offline startup differ by platform.
Offline data was not enough—the application itself had to boot offline
An installed PWA can retain valid restaurant data and still fail offline if the application shell, graphics engine, core bundle, session path, or required deferred code cannot start. Offline support therefore has two layers: the data must survive, and the application capable of reading that data must survive too.
Physical-device testing exposed conditions that browser-based acceptance had not reproduced. A same-origin engine dependency, offline PIN recovery, deferred loading, and version handoff all affected whether a previously installed application could reopen in airplane mode. The boot architecture evolved to keep the shell, Flutter engine, core bundle, default dashboard, fonts, and locales inside the boot package while preserving explicit session and update checks.
Chapter 5
What remains a product decision
The architecture now has explicit answers for several uncertain states. Closed beta still has to establish whether those answers match sustained restaurant use.
Trade-offs we chose
Availability vs integrity
More actions could theoretically be enabled offline. Some remain connection-protected when safe replay cannot be guaranteed.
Automation vs human review
Automatic reconciliation is convenient. When cash has already been collected and pricing remains uncertain, manager review can provide a clearer, more accountable resolution.
Abstraction vs visibility
The system could hide synchronization details. Sync instead exposes enough state for an operator to understand when work is waiting or requires attention.
Platform reach vs platform complexity
Supporting mobile, PWA, and desktop increases availability while introducing different boot, update, notification, storage, and offline constraints.
Current beta status
Sync is currently in closed beta in Syria. The current product demonstrates implemented system behavior, not yet validated adoption or commercial performance.
- Shared multi-restaurant operational context
- Arabic and English with RTL support
- SYP and USD configuration
- Role-based operational boundaries
- Controlled offline workflows and price review
- Stable retry identities and dependency-aware replay
- Sync Center recovery visibility
- Cached PWA boot and workspace recovery
- Real restaurant adoption
- Repeatable onboarding
- Pricing and packaging
- The frequency of operational edge cases
- Go-to-market assumptions
- Broader production hardening under sustained use
What is still unanswered?
- Which offline workflows are most useful in day-to-day restaurant operations?
- How often does manager reconciliation occur in practice?
- Is Sync Center understandable enough for nontechnical restaurant staff?
- Which role boundaries work in real teams, and which need adjustment?
- How much onboarding complexity is acceptable before restaurant owners lose interest?
- Which platform becomes the dominant operational surface in practice?