Skip to content
allanninal.dev/build
Collaborate

Part 1 of 7 · Fuel log auditor series ~6 min read

A fuel log auditor on AWS for a few dollars a month

A fuel report shows van seven doing eleven miles to the gallon and van eight doing sixty-two. Nobody is stealing anything; somebody selected the wrong vehicle at the pump on Tuesday and the two records swapped a tankful. Finding that in a week rather than at year end is most of what a fuel audit is actually for.

A beige concrete warehouse building with two loading docks and a dumpster
Photo by Raymond Kotewicz on Unsplash

Key takeaways

  • Most discrepancies are data errors, not dishonesty. Build for that.
  • Compare a vehicle against its own history, never against a fleet average.
  • Some checks are arithmetic: a fill larger than the tank is not a judgement call.
  • Raise a query with the driver first. It resolves most of them in one reply.
  • Designed on AWS for about $2 a month.

The whole system on one page

Before any code, here is the shape of what we are designing.

System: fuel transactions matched, checked and queriedThree boxes across the top sit outside the AWS account. On the left, Fuel transactions from a card provider or from receipts. In the middle, Odometer readings taken at the pump or later. On the right, The driver, who is asked rather than accused. Each connects by an arrow to the AWS account container below. Fills flow down into the account. Distance feeds in. One question goes back out. Inside the AWS account are three components in a row. On the left, the Matcher, working out which vehicle it really was. In the middle, the Checks, running impossible tests first and unusual ones second. On the right, the Query, a question with the numbers attached. A note at the bottom says the word on the right is query, and everything about the design follows from that.AWS ACCOUNTFuel transactionscard provider,or receiptsOdometer readingsat the pump, or laterThe driverasked, not accusedMatcherwhich vehicle,really?Checksimpossible first,unusual secondQuerya question,with the numbersfillsdistanceone questionThe word on the right is 'query'. Everything about the design follows from that.
Fig 1. Three things outside the account, three pieces inside it. The output is a question rather than a finding, and that choice shapes every component.
  • Compute
  • App integration
  • Analytics
  • People

Not a fraud system

Fuel fraud exists and it is a smaller problem than the industry around detecting it suggests. In a typical small fleet the overwhelming majority of odd-looking records are a mistyped odometer, a fill recorded against the wrong vehicle, a jerry can for the mower, or a receipt that never got submitted.

Building this as a fraud system finds exactly the same records and attaches a different meaning to them, and the cost of that is high: drivers who feel monitored stop volunteering the corrections that would resolve most of the queries in one sentence.

What runs (the inside)

  • The matcher. Establishes which vehicle a transaction really belongs to, which is less obvious than it sounds. Part 2.
  • The checks. Arithmetic impossibilities first, then deviations from the vehicle’s own pattern. Parts 3 and 5.
  • The query. One question to the driver, phrased as a question. Part 4.

One discrepancy, end to end

One fuel discrepancy from detection to resolutionA horizontal row of five boxes joined by arrows. Van seven fills sixty-eight litres when the tank is sixty. Impossible: arithmetic, not opinion. Query the driver: was this two vehicles? Reply: van seven and the mower. Resolved: split, and recorded. A note says it took ninety seconds of somebody's time, and the alternative is a year-end mystery.ONE DISCREPANCY, END TO ENDVan 7 fills 68Ltank is 60LImpossiblearithmetic, not opinionQuery the driver'was this two vehicles?'Reply'van 7 and the mower'Resolvedsplit, and recordedNinety seconds of somebody's time. The alternative is a year-end mystery.
Fig 2. The same system as one line. The third box is where a fraud-framed system would have gone somewhere much more expensive.
  • App integration
  • Machine learning
  • Management
  • People

In plain words

A transaction shows sixty-eight litres against van seven, whose tank holds sixty. That is not unusual, it is impossible, and the distinction matters: no interpretation is required and no judgement is being made about anybody.

So the query is a question with the arithmetic in it: “This fill was 68 litres and van 7’s tank is 60. Was some of it for something else?” The driver replies that they filled the mower’s can at the same time, which is entirely normal and was never recorded anywhere.

The record is split, the mower gets a fuel record it never had before, and the next time it happens the system knows this is a thing that happens here. That last part — learning the legitimate patterns rather than flagging them forever — is what stops the query list becoming noise.

Design rules that shaped every decision

  • Separate impossible from unusual, and treat them completely differently.
  • Compare a vehicle against its own history, never against a fleet average.
  • Ask the driver first, always, and ask a question rather than stating a conclusion.
  • Record the legitimate explanations so the same query is not raised twice.
  • Never compute a per-driver league table. It measures routes, not people.
  • The most valuable output is usually about a vehicle, not about a person.

Why this shape

Fuel is often one of the larger controllable costs in a small operation and the data is usually poor: odometer readings entered from memory, transactions matched to vehicles by a card number that gets swapped, and receipts that arrive in a carrier bag once a month.

Cleaning that up produces two things worth having. The obvious one is an accurate cost per mile. The less obvious and usually larger one is early warning about vehicles: a van whose economy has fallen eight per cent over four months has something wrong with it, and that is visible in fuel data months before it is visible anywhere else.

The next four posts walk through each piece: how a fill gets matched to a vehicle, why fuel economy only means something against itself, how a query gets raised without an accusation, and what the fuel data says about the vehicles. One diagram per post, a cost breakdown, and an engineering reference at the end.

All posts