AggFlow Reader

The problem

Quarries and gravel pits design their plants in a program called AggFlow, which produces a PDF describing the setup — how many tons per hour, what material, how the rock breaks down by size, and what each screen deck is supposed to separate out.

Selling them the right vibrating screen means checking whether the machine has enough screen area for that tonnage. The industry method comes out of a handbook and involves looking up nine correction factors in tables, interpolating between rows, and multiplying them together. It's a page of arithmetic per deck, and getting one factor wrong gives you a machine that looks correctly sized and doesn't work in the field.

Two people here could do it reliably. Everyone else either waited for them or skipped the check.

What it does

It reads the AggFlow PDF and pulls out the feed rate, the material, the size breakdown and what each deck is cutting at. AggFlow produces two noticeably different layouts depending on how the plant was drawn, so it handles both.

When it can't find something, it says which thing by name — "feed rate not found, please enter manually" — rather than defaulting to a number and producing a report that looks complete but isn't. That turned out to matter more than how accurate the reading was.

From there it runs the sizing calculations and shows all the intermediate numbers, not just the answer, so the engineering report can show its work. A separate part suggests the actual screen media by product number, taking into account how coarse and abrasive the material is and whether it's being screened wet.

Five versions of finding out what people wanted

Version one had a calculator, PDF import, and one report. Version five has three separate reports, and that's basically the whole story of the project.

Nobody asked for three audiences up front. You find that out by handing the engineering report to a salesperson and watching them hunt for the one number they care about, buried under nine correction factors. Then you find it out again when the sales version goes to a customer with internal assumptions sitting on page two.

What's interesting looking back is which parts moved. The reading and the math barely changed after the first couple of versions — that part was right early. Everything after that was about how to communicate it.

The mistake that changed how it's built

A report went out to a customer listing screen media — specific products and materials — that nobody had actually selected. It also recalculated the machine's utilisation figures based on that media, so those numbers were wrong too.

It wasn't a typo. The tool lets you choose media yourself, and it also suggests media. Somewhere in building the report those two things had ended up in the same place, so a suggestion got printed where "this is what was chosen" belongs.

The fix was to keep those two things separate everywhere they appear, clearly label the suggestion as a suggestion, and write down why the code looks slightly redundant — so that whoever changes it next, probably me, doesn't undo it. That note is the most useful thing in the whole project, because it's what stops the same mistake happening twice.

A couple of decisions I'd defend

The calculator is a web page in a desktop window. It looks and behaves like a normal Windows program, but the actual calculator is built the way a web page is, which made a fairly complex form much easier to lay out and much easier to change. It installs as a single application and it's small.

The handbook knowledge is stored as data, not buried in code. The factor tables and the media selection rules sit in their own files, structured like the tables they came from. That's what makes the tool worth anything, and keeping it separate means correcting a factor is a one-line change instead of an afternoon of hunting.

The AI in it doesn't touch the numbers. There's a short written comment on each result, and it's specifically instructed not to restate any figures. It interprets; it never calculates. Given what the tool is for, that line isn't negotiable.

What it still needs

Five folders instead of five proper versions. V1 through V5 are literally copies of the folder, which means a fix has to be made in up to five places. This is the clearest example of the version control gap I mention on the about page.

No automated testing. The media mix-up was exactly the kind of thing a test would have caught before a customer did.