A field-force and distribution platform for a distributor selling to retail shops in Pakistan: geofenced shop visits, delivery and cash collection, a warehouse stock ledger and double-entry finance. I built ten of its 31 modules, 334 of its 474 API endpoints, and the controls that keep its stock, cash and access correct.
* FIELD, STOCK AND BOOKS
[01] The problem
A distributor works away from its office: salesmen visit shops and book orders, riders deliver and collect cash, and stock moves between warehouses. In the base platform, a visit's GPS was never compared with the shop's location, and an edit could mark a visit complete with no proof at all; stock was a single number per product that orders drew down and only an admin's typed figure could raise; and there were no books. Visits, stock and cash all had to become checkable, and money had to reach a ledger only through a controlled posting.
[02] The constraints
Production runs on MongoDB Atlas, where multi-document transactions work; the test and migration databases are standalone, where they do not. Correctness had to live in idempotency keys and compensation, using a transaction only where one exists.
Role checks were hard-coded at nearly 200 route call sites, and the admin app kept its own copy that disagreed with them. Moving to one permission matrix had to keep every existing grant as it was, apart from changes made on purpose.
Finance had to land in a running business without disturbing it. Every automatic posting ships switched off, so finance can be deployed long before it is turned on, one event at a time, with the nightly control checks watching.
[03] The approach
The client's specifications set the rules: what a stock movement may do, that the admin's final approval is the posting, who may do what. My part was making those rules hold: every stock movement goes through one guarded function with a replay key on every row, every finance posting through one engine, ten control checks run every night, and the permission matrix is held to a parity test against the access that existed before it.
[04] The trade-offs
[01]
[02]
[03]
[04]
[05] The build
[01]
Where a shop has a saved location, salesmen must check in within 150 m of it, an order taken on a visit must be booked while checked in, and checkout still takes a shop photo, a selfie and their GPS position. Time on site is recorded with a 30-minute overstay flag, a warning comes before a skipped visit drops them below 75% completion, and a salesman not checked in by 12:30 is frozen.
[02]
Receipts, orders, transfers, damage and counts all move stock through one function: never below zero, all lines or none, a replay key per ledger row and an audit row per change. Stock sits in three buckets per warehouse, sellable, in transit and damaged, and every balance is checked against its ledger each day.
[03]
All seven kinds of finance document, from vouchers and bills to payroll runs and staff advances, go to the admin for final approval through an optional review their maker cannot perform. That approval posts a balanced double-entry journal across a seeded chart of 53 ledgers, and a refused posting stays on the document with its reason. Every finance report exports to PDF, Excel and print.
[04]
Every night, ten control checks prove the books against the records behind them: what shops owe, what riders hold, online payments in transit, stock on the shelf, in transit and out for delivery, goods received but not billed, what is owed to suppliers and staff, and the advances staff owe back. Any drift blocks the month from closing, reported with its account, its amount and the day it first appeared.
[05]
The client required an admin-editable permission matrix. I seeded it from the backend's own route guards, replacing nearly 200 hard-coded role checks, kept admin outside it so nobody can lock themselves out, and gave people with several roles an admin-defined profile. A parity test checks the seed against who could reach each of the 228 endpoints that existed before the move.
[06]
Per-employee analytics, monthly targets and region-sales drill-downs, with grand totals over the whole dataset on the report tables, carried into every export.
[06] What broke
!01
In production, the rule exempted anyone with no visits generated for the day. Visit generation had stopped three weeks earlier, so from launch every salesman was exempt every day and late starters kept taking orders after 12:30. The exemption came out two days later, and an idle generator now shows up as a count.
!02
A change of mine left returns out of what a shop owed, so the rider's screen overstated each balance by the value of every return, and the recovery cap, set from that figure, could let a rider collect money the shop did not owe. Building the receivables control check surfaced the gap, and the fix matches the ledger line for line.
!03
The base platform's product catalogue carried its creator's salary, home address and phone to salesmen and riders, and changes of mine added the last purchase rate to it and widened an unscoped visit list to more roles. Order taking now uses a picker that returns only what an order needs, visits are limited to the staff a caller may see, and tests assert both.
!04
Before finance went live, a reversal copied the source of the entry it undid, so a query for a document's live posting also found its reversal. A test written before the fix showed two edits to one goods receipt leaving 7,200 in inventory where 6,200 was right.
[07] The result
119
Access errors caught pre-release
* endpoint–role pairs: 83 lost, 36 gained
10
Nightly control checks
* finance, pre-launch; drift blocks the close
28 / 30
Finance acceptance scenarios
* from the client's specification, under test
1,640
Automated test cases
* in 73 suites; the base build had none
These are pre-release verification results, not business outcomes: the distributor's volumes are its own, and nothing was load-tested. The 119 comes from the parity test's first run over the 228 endpoints that existed before the matrix; the control checks and acceptance scenarios belong to the finance module, built but not yet live; test and endpoint counts are static, at the repository state of 1 October 2026.
[08] What I’d do differently
I'd write the suites before calling a module done. The permission tests came afterwards and found 119 access errors the diff had hidden, and the suites still run by hand rather than in CI.
Need something like this built?
Next case study [08]
mailagent
Human-in-the-Loop Scheduling Agent
Read the case study →
