The Supabase backend - Comfort Hub handbook

Supabase is the engine. It holds the database every other system reads, runs the sync with Zoho in both directions, and runs the workers that talk to QuickBooks, Twilio, Stripe, Resend and the app. The app, the pay page and the website talk only to it.

The parts

Part	What it does
The database	One row per customer, account, lead, property, piece of equipment, work order, invoice, payment and so on, plus a crosswalk that remembers which Zoho record each row mirrors
The webhook door	One address Zoho, Stripe and Resend post to. Each notification is written down first, then queued. Twilio has a door of its own on the phone function. QuickBooks posts nothing: payments taken on the pay page reach QuickBooks through Helcim’s own accounting link
The sync worker	Drains the inbound queue (Zoho’s notifications) and the outbound queue (our changes to push to Zoho). Woken by the door and, as a backstop, once a minute
The action worker	Runs the follow-ups a change triggers: the QuickBooks customer, the property imagery, the technician invite, the emails. Same wake pattern
The monitor	Three workers woken once a minute that run every check, hold each problem open as a condition until it is gone, and hand each one to Sentry. The checks are on Monitor checks; how it works is on How the monitor works
Scheduled jobs	The once-a-minute wakes, the nightly clean-ups, the reminders and pushes; see Scheduled jobs
The ledger	Every attempt at every outside system is one line, with its outcome. The monitor and the human-review list read from it

The engine holds one Zoho login token, shared by every worker and refreshed when it expires. Zoho refuses a refresh when too many arrive in a row, and scripts run by hand against Zoho use the same allowance.

A blocked refresh shows as one urgent Deliveries and logins condition, “oauth: credential rotation is blocked”, so one Sentry issue and one email.
A queued message gets 10 tries with a growing pause between them, so the queue rides out a brief refusal on its own. Past the tenth try the message becomes a dead letter; see Redrive a dead letter.

Two scripts refreshing the Zoho login within a few minutes of each other trip the CRM’s limit, and inbound sync stalls until the refusal lifts.

Backups

Supabase keeps a daily physical backup of the database. Point-in-time recovery is switched off. A plain logical dump does not include the queue tables, because they belong to the queue extension rather than to our schema, so a restore rehearsal must start from a physical backup.