webapp Case study
Gold Wallet / Jewelry Ledger
A gold and jewellery business holds customer value that is not simply cash: deposits against a piece, credit from a trade-in, promotional balance from a campaign. Treating all of that as one number in one column is how a shop ends up unable to answer what a customer is actually owed.
The business problem
Customer value in this business arrives from several directions and each kind behaves differently. A deposit against a specific piece is not spendable elsewhere; a trade-in credit may be; a promotional balance expires. Collapsing them into one balance makes the arithmetic easy and the questions unanswerable, and those questions are exactly the ones that come up in a dispute.
What I delivered
- A ledger model where every movement is an entry with its own type, and the balance is derived from those entries rather than maintained alongside them.
- Typed value categories so that deposit, credit and promotional balance stay distinguishable at every point, including after they are partly spent.
- Transaction review that reads as a sequence of movements with causes, which is what makes a customer conversation about a balance possible.
- Exact integer arithmetic throughout, so reversals cancel their originals precisely rather than approximately.
- An audit trail as a property of the design rather than a separate log, since the entries themselves are the record.
Technical approach
- Append-only. Nothing is edited or deleted; a correction is another entry, which is what keeps the history honest.
- The categories are modelled explicitly rather than encoded in a note field, because a category you cannot query is a category you will get wrong.
- Balances are computed. This costs more on read and is the only structure where the answer to how did we get here exists at all.
- Money never touches floating point. In a business priced by the gram, accumulated rounding is not a rounding error, it is a shortfall.
Result and evidence
Customer value became explainable. Any balance can be walked back through the entries that produced it, which is the property that matters when a customer disagrees with a number.
Commercial value
In jewellery retail, the balance conversations are high-value and infrequent, which means they are exactly the ones you cannot afford to lose. An auditable ledger is what makes the shop's position defensible.
Readable implementation brief
implementation_brief {
project: "Gold + Jewellery Wallet Ledger"
model: "append-only entries; balance derived, not stored"
categories: "deposit / trade-in credit / promotional,
typed and queryable, not free-text"
corrections: "a new entry, never an edit or delete"
arithmetic: "exact integers; no floating point on money"
audit: "the entries are the record; no separate log"
answers: "how did this balance get here, entry by entry"
}What this project shows
The reason to build this as a ledger rather than a balance field is not elegance, it is that the shop will eventually need to defend a number to a customer.
Modelling value categories explicitly costs more up front and prevents the class of bug where a deposit against one item quietly becomes spendable against another.