Joe BaltazarLet’s talk
All work

Case study · Good Code at rebootthefuture · 2024 — now

A restaurant POS that can’t go down during dinner service, or get the money wrong.

Good Code POS item editor on an Android tablet
The POS item editor: modifiers, course, dining option, discount and price adjust. Android tablet, landscape.

The stakes

Two halves, one database.

A stalled login costs table turns. A card sale recorded as declined when the terminal approved it means a guest charged twice. A report that quietly drops rows sends the wrong numbers to payroll.

The POS

What servers, bartenders, cashiers and guests touch: orders, kitchen tickets, split checks, card terminals, tips, drawers and closeouts. Offline-first on Android tablets, handhelds and self-order kiosks, so service keeps going when the internet doesn’t.

The dashboard

The back office for owners and managers: menus and pricing, staff and permissions, floor plans, online ordering, reports and integrations. It also owns the database migrations shared by the POS and the kitchen display.

  • ~1,585Dashboard commits, about 28% of the repo
  • ~690POS commits, about 15%, from the repo’s first month
  • 3Form factors on one codebase: tablet, handheld and kiosk

01 — Payments

“Uncertain” is not “declined.”

The terminal approved a sale and the provider recorded it, but the terminal proxy answered with a communication error.

54 → 0

Sale attempts at 5 restaurants in 60 days ended on these codes, each one a possible double charge. They now go through a durable uncertain state, never a blind retry.

Problem

The POS treated every communication error as a rejection. It marked the payment failed and allowed a new attempt under a fresh reference the gateway couldn’t de-duplicate.

Decision

Timeout and comms-error codes write a durable UNCERTAIN marker, then ask the terminal for the sale’s status by our own reference: a short settle, then up to 3 polls. Pre-authorisations keep their hold, and a recovered sale prints the same receipt data as a live one.

Why it matters

It’s the difference between a guest charged once and a guest charged twice. Tip adjustments got the same care: an outsized tip and a tip below the captured amount each need their own confirmation.

  1. Card sale
  2. Timeout or comms error
  3. UNCERTAINdurable marker
  4. Status checkby our reference · up to 3 polls
    • Recorded
    • Confirmed not charged
    • Sent to manual check

See the pattern in code (GitHub, opens in a new tab)Rebuilt from scratch with a fake terminal: the state machine, crash recovery, and a test for every failure path.

Good Code POS payment screen with card and cash prices
Payment: dual pricing (card vs cash), split, service charge and gift card.

02 — Offline-first under load

Reads stopped waiting behind sync.

Local SQLite synced with PowerSync keeps service running through network drops, until sync itself becomes the bottleneck.

≈1 s

Taken off the login screen and the order and floor views on busy restaurants.

Problem

PowerSync commits on the single SQLite write connection and can hold the lock for about 10 seconds on busy restaurants. Reads queued behind it.

Decision

Hot-path reads moved to the read pool, and the rule became explicit at the storage layer: reads through withRead, writes through a retry-aware single writer.

Sync integrity

A write was uploaded as the anonymous role while the offline session cache said “signed in”. The upload guard now requires a live session and never dead-letters those writes.

Good Code POS restaurant login showing offline sync progress
First sign-in: PowerSync downloads about 121k operations so the station can run offline.

03 — Reports and integrations

Numbers that scale, partners that prove delivery.

External APIs lie politely: a 202 that means nothing, a row cap that never says it truncated.

9 → 1

Report requests

Daily Sales chunked ticket IDs by 300, so cost grew with tickets, not rows. A tenant-scoped helper now counts first and takes the cheaper path. Earlier, I stopped report lists being cut off at PostgREST’s 1,000-row cap.

2,900+

Mappings kept

Moving a restaurant from a 7shifts token to OAuth used to mean disconnecting and losing 2,111 receipts, 747 punches and 85 employees’ mappings. An in-place OAuth upgrade keeps them all.

Outbox

Proof of delivery

NowBookIt answers “202 Accepted” even when it rejects a sale. A transactional outbox (pending → processing → sent → confirmed or dead) with backoff and reconciliation only counts a sale once it appears on their side.

Good Code dashboard reports list
Reports, grouped, including OnePOS-style summaries.
Good Code dashboard third-party integrations
Integrations: 7shifts, NowBookIt, OpenTable, Nory and gift cards.

04 — Guardrails

Encode the rule, not just the fix.

Fixes land with the rule that prevents a repeat, so the next engineer, or AI coding agent, can’t reintroduce the bug.

Integrity sweep

A scheduled, read-only sweep checks 7 invariants against live data, compares them to a per-environment baseline and reports drift to Sentry. It catches damage that’s already stored, not just new damage.

Ratcheting CI

Typecheck and lint drift checks fail only on new problems, so legacy code improves without blocking feature work. Preview deploys of a branch’s edge functions go to dev only.

Delivery safety

No laptop writes to staging or production; deploys go through CI and promotion. When a revert broke bundling on every PR, I traced it and fixed it without bringing the reverted code back.

Screens

One system, from the kitchen to the back office.

Dev environment, test restaurant. Today’s figures read $0 because the business day had just started.

Good Code dashboard home
Dashboard home: today’s revenue, labor and quick actions.
Kitchen order routing settings
Kitchen order routing to printers and KDS stations.
Receipt designer with live preview
Receipt designer with live preview.
Online ordering setup
Online ordering storefront and setup readiness.
POS split check
Split check: evenly, by seat or by item.
POS server closeout report
Server closeout report.

What I learned

Offline-first changes what “correct” means.

  1. Clear rules beat case-by-case fixes

    With local SQLite, a sync engine holding locks and sessions valid offline but not online, the hard bugs are about who wrote what, and when.

  2. External APIs lie politely

    Design for proof of delivery: outboxes, reconciliation and uncertain states.

  3. Three form factors, one behaviour

    Tablet, handheld and kiosk share hooks and the ticket state machine, so a pricing or tax fix can’t land on one and miss the others.

  4. What I’d push for next

    Contract tests for every payment and integration partner, and performance budgets on the hottest POS screens, so regressions show up in CI rather than during service.

Next story · Overwatch via NTERSOLWildfire exposure for insurers, on a phone and on the webRead the story