Architecture · FS-03
Restaurant Revenue Reconciliation Engine
ARCHITECTURE · $8K–$15K PROJECT BANDThird-party orders reconciled against the point of sale as they land, mismatches queued for dispute with the evidence attached, prep quantities adjusted from last week's same-day demand, a labour forecast that warns before overtime rather than after, and a tip pool calculated to the federal rules.
Every figure in this console is sample data, shown to demonstrate the interface. It is not real client data and not a performance claim.
The problem this is shaped around
Three delivery platforms each take a cut, each occasionally take the wrong cut, and each have a dispute window that closes quietly. Nobody has time to check an order-level fee against a point-of-sale ticket, so nobody ever does.
How work moves through it
Stage 1
Order arrives from a platform
Platform payload stored whole, then matched to the point-of-sale ticket on time, total and items rather than on an identifier the platforms do not share.
Stage 2
Fees compared
Expected commission for that platform and order type computed independently and compared to what was actually deducted.
Stage 3
Mismatch queued
A discrepancy becomes a dispute record with the two figures and the source documents attached, ready to file in one action.
Human step
Owner files the dispute
The system prepares; a person submits and decides which are worth pursuing.
Stage 5
Outcome recorded
Win and loss recorded per platform, so the restaurant learns which disputes are worth the time instead of guessing.
Gold marks a step a person takes. There is always at least one, on purpose: the system prepares and displays, a human confirms and executes. That is the rule for money movement and for anything a model extracted from a document, and it is not negotiable on a build.
Decisions taken at the schema, not retrofitted
The raw platform payload is kept, not just the parsed fields
Platforms change their fee structures and their field names without notice. A parsed-only record cannot be re-examined after the change, which means every historical dispute becomes unarguable.
Tip pool rules are configuration, not code
The federal rules on who may share a pool differ by whether a tip credit is taken. A restaurant that changes its model must be able to change the rule without a deployment.
Every file is bound to the record it belongs to
A photo, receipt or signed document is stored with a pointer to the specific job, invoice or claim it belongs to, plus who uploaded it and when. The test is whether searching a transaction a year later surfaces its own proof automatically. A folder of unlinked images fails that test, and it is the state most businesses are in.
One database per client, not shared tables
Each build runs in its own container against its own database with its own credentials. Isolation by table prefix inside a shared database is the mistake this replaces: it works until one missing filter in one query shows a business its competitor's numbers, and by then the whole schema depends on it.
Where it breaks, and what it does about it
Anything can be made to work on a good day. This is the list that decides whether a system survives a bad one — and the honest cost of each answer, because none of them are free.
| When this happens | The system does this | What that costs to build |
|---|---|---|
| A delivery order has no matching ticket | It goes to an unmatched queue rather than being force-matched to the nearest candidate. A wrong match is worse than no match, because it silently justifies a fee that should have been disputed. | Somebody works the unmatched queue. It is real weekly labour and the proposal says so. |
| A platform changes its fee schedule | Expected-versus-actual drifts across every order at once rather than on one, which is a different shape from a single error and is surfaced as a schedule change to confirm, not as hundreds of disputes. | Anomaly detection across the batch, not just per record. |
| The dispute window closes before anyone looks | Each platform's window is stored per platform and the queue is ordered by time remaining, not by size. The largest discrepancy is worth nothing once it has expired. | Per-platform deadline rules that need maintaining as platforms change them. |
What this deliberately does not do
- It does not file disputes automatically. It prepares them; a person decides and submits, because an automated dispute against a platform a restaurant depends on is a business decision, not a data one.
- It does not set prices or menu strategy. It shows what each channel actually nets.
- The prep forecast is a suggestion built from demand and weather. A kitchen overrides it freely and the override is what teaches it.
- It calculates the tip pool to the configured rule. Whether that rule is correct for the restaurant's tip-credit position is a question for their employment counsel.
Book an architecture scoping session
An hour on your actual operation — where the work currently queues, what gets re-keyed, which step everyone has quietly built a spreadsheet around. You leave with a diagram like the one above drawn for your stack, whether or not you build it here. Scope is written before any payment, always.
The linked walkthrough is an interactive demo, not a deployment: it runs entirely in your browser with sample data and resets when you refresh it. This page describes the architecture built when a business commissions the system — not a claim that this particular one is running anywhere. Systems are built on infrastructure we operate, and your data stays yours and is exportable on request at any time, including if you leave.
FS-03 · restaurant-revenue