Architecture and consulting

Deposits, holdbacks and progress claims that reconcile

Deposits, the standard 10% construction holdback and statutory declarations had no home in the org. The ledger that fixed it stores every amount as a positive number and puts the sign in the type.

Built for: SMT Research, Vancouver
Service line: Architecture and consulting
Window: Jun to Sep 2026

The headline number5 of 45Projects with any deposit accounting before we startedDeposits were held on roughly 45 projects. The org tracked them on five orders.

01Key numbers

What we measured

~45Projects carrying a customer depositRecorded as roughly 45, not counted exactly. Five of them had deposit accounting in the org.

4Ground-truth constraints verified before designingEach one checked against the live system, not assumed from the schema. This is why the design held.

10%Standard construction holdback, now retained rather than chasedThe standard construction holdback rate. It stops appearing in overdue receivables.

$0.00Deposit balance forced on the final drawFinal-draw reconciliation drives the remaining deposit to exactly zero rather than to a rounding tolerance.

02The situation

What was true before

The firm held deposits on roughly 45 projects. The org had deposit accounting on five orders, no unearned-revenue ledger, no holdback field, no statutory declaration and no compliance tracking.

The standard 10% construction holdback was showing up as an overdue receivable, which made the ageing report unusable for the one thing an ageing report is for.

Recognise this in your own org?

Start a diagnostic See the service lines

03What we built

The mechanism

An append-only event ledger, and a deduction that hooks the invoicing path people actually run.

Every amount stored as a positive magnitude

The ledger is append-only and stores each amount as a positive number, with the meaning of the sign carried by the type field. Rollups then cannot produce a sign-convention bug, because there are no negative numbers in the store to invert.

The deduction hooks the path users actually run

The live invoicing path does not write to the invoice objects at all. It renders a PDF and flips a flag on consumed product. Any proportional deposit deduction therefore had to hook that path. The parallel invoice objects are mirrored and never made load-bearing.

A deduction formula small enough to check by hand

Deduction is the lesser of the affected subtotal multiplied by the deposit rate, and the remaining deposit. Final-draw reconciliation forces the balance to exactly zero. A controller can verify one invoice with a calculator.

The accounting stance written down for sign-off

The treatment is documented before it is built, including the alternative treatment that was not chosen and the reason. An accounting decision made silently inside a trigger is a decision nobody agreed to.

Sales and Forecasting

How the projection is built

Backlog, remaining to bill on open orders100%

−Marked finished, nothing left to bill24%

=What the engine spreads across months76%

+Open pipeline at 75% or better, not signed2%

=Projected78%

What this number does not vouch for

49 ordersare past their end date and still counted as fully billable, with nobody having marked them finished.

23 ordershave no billing window at all, so their placement is the weakest rule in the engine.

9 orderswere invoiced past their contract value, and each one is named rather than netted off.

Depiction · A revenue forecast that prints its own arithmetic. Every row carries the method that placed its dollar, so a controller can defend the total line by line.The panel on the right is the part most forecasts omit: the amounts the engine will not vouch for, published beside the number rather than discovered in an audit.

Surfaces built

We will demonstrate any of these live, on the real org,.

Deposit event ledger with type and magnitudeImage withheld
Progress claim PDF with the deposit deduction lineImage withheld
Holdback retention against an ageing reportImage withheld

The finding

The invoice objects were not where invoicing happens.

The obvious place to hook a deposit deduction was the invoice object. Checking first showed the live path never writes there. It renders a PDF and flips a flag on consumed product. Building against the object would have produced a feature that worked in test and did nothing in production.

04Outcome

What changed, verified

Shipped in two phases with every deploy green, and the deduction is a pure no-op on an order that has no deposit.

Deposits, holdback retention, progress claims and statutory declarations exist as records rather than as habits.
Existing invoices are unchanged, because the deduction does nothing when the deposit is zero.
The 10% holdback stops appearing as an overdue receivable.
The alternative accounting treatment is documented alongside the chosen one.

How it was verified

The generated PDFs were verified end to end on live records, and every piece of test data created for the check was deleted afterwards.

Sources

docs/research/01-salesforce-platform.md §2.6 · Construction billing
docs/research/01-salesforce-platform.md §4 · The hard rule on done

Keep reading

Two more

All case studies

Architecture and consulting
3Of finished work that had never been invoicedThe gap between what one system called installed and another called invoiced, on a book all three agreed the size of.
A forecast the CFO can defend line by line
Three systems agreed on the size of the book and disagreed on how much of it was done. The gap was work physically finished and never billed.
Custom development
31%Of quote lines carried no tax code5,997 of 19,255 lines. 5,182 of them sit on Canadian job sites.
A tax engine rebuilt from 28 rows of configuration
The client told us the tax was calculating by product instead of by province. We tested that against all 2,335 order line items and it was not true. Six other defects were, and we priced each one.

Next step

Bring us your hardest Salesforce problem

Tell us what is broken. You get a written read on it within one business day, before any money changes hands.