01  The brief

What the research was for

To decide the best way to build and run your dashboard: where the numbers come from, how they get in every night without anyone touching them, how the totals stay honest enough to run a season on, and how to build it so that adding Portland later is a small change rather than a second build.

One thing to say up front, because it shapes the whole list: Clover knows what you sold, Homebase knows what your staff cost, and between them they cover almost everything you asked for. Almost. Where the line falls — and the two good ideas we are deliberately leaving until after the first season — is decision 06.

02  Method

What we looked at

Eleven primary sources, read directly rather than summarized: the official Clover developer documentation and the Homebase public API specification, endpoint by endpoint, down to the field-level limits that decide how this gets built. No blog posts, no comparison articles. Six decisions to settle, the same six we make recommendations on below:

• 01How the numbers get in
• 02The database behind it
• 03Loading the history
• 04Where it lives, and who can see it
• 05Proving the numbers are right
• 06What we are not building yet

03  Findings

What we found

How the numbers get in

The tempting shortcut is to have the dashboard ask Clover and Homebase for the numbers the moment you open it. That breaks in three ways. The page would wait on two outside systems every time it loaded. Both systems cap how often they will answer at all, and neither will hand over more than a slice of your history in one go. And a dashboard built that way has no memory: if Clover is slow on a Saturday night, there is simply nothing on the screen.

So the dashboard keeps its own copy. Once a night, a small job asks each system what changed, writes it down, and stops. It pulls from two places, because the two halves of the answer live in two places.

• Clover has the sales. Every order and payment: the total, the tax, the tip, the refunds, which items were rung up, which employee rang them, and a field that separates real sales from voids and failed cards.
• Homebase has the labor. Actual clock-in and clock-out per person, what a shift was scheduled to cost, and what it actually cost. Homebase does the wage math itself, overtime included, so we read its answer rather than rebuilding it.

Two details are what make that job trustworthy rather than merely automatic. Every record is filed under the ID its own system gave it, so running the job twice updates the same row instead of writing a second one. That single property means the sync can be re-run any time, after any interruption, without ever double-counting a dollar. And it asks each system for what changed, not for what is new — so a timecard corrected on Tuesday for Saturday's shift gets picked up rather than missed, and a shift deleted at the source gets removed here too.

The database behind it

Sales and labor land in one managed database (Supabase), the same kind that runs your allergen assistant. What goes in is deliberately plain: the raw facts, and nothing else. Not one metric is ever saved. Labor as a percentage of sales, sales per labor hour, this Saturday against the same Saturday last year — each is a stored question that recalculates every time you open it. A number built that way cannot go stale, because it never sat still long enough to.

Money is kept as whole cents from the register all the way to the screen, and turned into dollars only in the last inch. Fractions of a cent drift when they are added up a hundred thousand times, and you are exactly the person who would find the penny.

The two systems are joined on store and on day, and for the per-person numbers, on the person: Homebase carries the Clover employee ID on each of its records, which is the one field that makes "orders per person" possible at all. We confirm it is actually filled in on the first real pull, and if it is not, a small mapping table does the same job by hand.

Loading the history

Clover will not return more than ninety days of history in a single request, no matter how you ask. Several seasons of Bar Harbor therefore cannot be fetched; they have to be walked. So loading your history is a separate job from the nightly one. It steps backward through your seasons ninety days at a time and writes a checkpoint after every window, so a dropped connection three hours in resumes where it stopped instead of starting from the beginning. It runs once, from a laptop, and is then put away.

Keeping it separate is the point. The nightly job stays small, fast and boring, which is exactly what you want from something that has to run unattended for years. This was also the biggest thing the research changed: the first instinct was one job doing both, and the ninety-day limit makes that a bad idea. The same design has a quieter benefit — because the nightly job asks for everything since it last succeeded, a missed night, or an entire closed winter, costs nothing. The next run catches up on its own.

Where it lives, and who can see it

Cloudflare hosts the dashboard, the same place your allergen assistant already runs, which keeps both on one bill and one set of habits. Two logins, yours and Natalie's. Every row in the database is stamped with which store it belongs to, and the database itself enforces who may read what — the same wall we built to keep shops separate in the assistant. That wall is also what makes Portland an addition rather than a rebuild: it arrives as a second entry in a list that already exists, with its own sealed section beside yours.

The security line that actually matters here is not the login. It is the keys. Your Clover token and Homebase key can read every dollar your business has ever taken. They live in exactly one place — server-side, inside the nightly job. They are never in the dashboard, never in the browser, and never in the code we keep.

Proving the numbers are right

Two things are usually treated as polish, and they are not. The first is an alarm: if the nightly sync fails, it has to say so out loud. Without one, a broken sync does not look broken — the dashboard keeps opening, keeps drawing charts, and quietly keeps showing last Tuesday. That is worse than an error, because you would act on it.

The second is a reconciliation check: every day, the dashboard's own totals are compared against Clover's own reporting, and a mismatch gets flagged before you ever see it. This catches the three mistakes a system like this actually makes — a day filed under the wrong timezone, a void counted as a sale, a seam between two windows of history where a few hours went missing. It is the difference between a dashboard you glance at and one you make decisions from. The first figure that is wrong is the last one you trust.

What we are not building yet

Three good ideas came up that are not in version one, and the reasons are different in each case. Naming them here is deliberate: a thing left out on purpose reads very differently from a thing forgotten.

• Food cost, gross margin and prime cost — out of reach, not out of scope. This one is not a scheduling call. Clover knows a pint sold for twelve dollars; nothing in either system knows what the cream in it cost you. That answer needs invoices, recipes and yields, kept up to date by hand, which is a second source of truth and its own project. There is a smaller version of the same gap on the labor side: Homebase reports gross wages only, with no employer taxes, so even fully-loaded labor needs one number from you before it is true.
• Asking your numbers in plain language — deferred by sequence, not by difficulty. Because everything lands in an ordinary database, you will already be able to ask it questions in plain English through your own Claude account; the capability arrives free with recommendation 02. The reason to wait is that you cannot tell which questions a fixed dashboard fails to answer until you have used one for a season. Build the freeform layer first and we would be guessing at the gaps instead of filling the real ones.
• Outside market context — deferred because it is a different machine. Milk and cream pricing, or public comparables, would come from sources neither of your systems controls, on their own schedule, with their own ways of failing. Bolting that onto the nightly job would make the one piece that has to stay boring interesting. It belongs beside the dashboard, later, not inside it.

One more thing on this list is not really a deferral: Portland. Every row carries its store from day one and the access rules are already written per store, so the second shop is a configuration change and a backfill, not a second build. The store-versus-store views simply switch on when there is a second store to compare.

04  The call

What we recommend

05  Receipts

Sources

Grouped by decision. Open any drawer to see the specific pages behind that call, and click through to read any of them.

Two standing notes. First, everything above comes from official documentation and the live API specification rather than third-party summaries — but a specification describes what these systems can return, not what your registers have recorded. Six things only your own data can settle: whether an order total already includes tax, exactly how a double is labelled, how comps and discounts show up, which order states count as sales, whether Homebase is already carrying your Clover employee IDs, and how many seasons Bar Harbor has been on Clover. We answer all six by reading ten real orders on the first day we have keys, before a single table is built. Second, the alarm and the reconciliation check in recommendation 05 are the one place we cite no document. No API tells you to build them; they come from what goes wrong when nobody does.