A Docblock That Was Aspirational
A comment on the till code promised that failed fiscal filings were reconciled with a manual button. The comment had been copied from the invoice flow, which had one. The till did not, and the job gave up after three attempts.
The most trusted document in a codebase is a comment written by somebody who understood the system, and the most dangerous one is a comment written by somebody who understood a different part of it.
What the comment said
That when a sale is recorded it is filed automatically to the tax authority, queued after the database commit so that fiscal filing can never block a sale, fully idempotent, and reconciled with the manual button.
Three of those four were true. The sale is not blocked by filing, which is the right call — a shop must be able to sell when a government endpoint is slow. It is idempotent. It is queued after commit.
There was no manual button. The paragraph had been copied from the customer invoice flow, which has one, into the till flow, which did not.
What that meant in practice
The filing job retries and then stops after three attempts. Without a manual retry and without a sweep, a sale whose filing failed sat marked as failed indefinitely: no control on any screen, no route to trigger a retry, and nothing scheduled to come back for it.
The sale itself was fine. The money was taken, the stock moved, the receipt printed, the books balanced. Only the fiscal transmission was missing, and it was missing quietly, on a record whose own documentation said it would be recovered.
Sale recorded
Complete and correct. Never blocked by the filing.
Filing queued after commit
Correct design — a slow authority endpoint must not stop a shop trading.
Automatic retry
Three attempts, then the job stops. Reasonable on its own.
Manual retry
Promised by the comment. Did not exist until it was built.
Scheduled recovery sweep
Not implied by anything, and the actual missing piece. Now runs hourly.
The docblock was not wrong about the system. It was right about a different part of the system, which is a much harder kind of wrong to see.
Why both halves were needed
A manual button alone is a control that depends on somebody noticing. A failed filing produces no symptom at the counter, so nobody would look until a return was being prepared — by which point the number of failures is a project rather than a click.
A sweep alone is better but leaves no way to force a retry after a specific problem is fixed. Both were built: an hourly command that finds failed filings and retries them, and a control that lets a person retry one deliberately.
And then the comment was rewritten to say what is true, with a note recording that it had not been. That last part is the habit worth having. A corrected comment with no history invites the same copy again.
What AWRA OpsHub does today
- Automatic filing of a till sale to the Kenyan tax authority where the tenant has it enabled, queued after commit so a sale is never blocked by it.
- Idempotent filing, so a retry cannot double-file a sale.
- A manual retry control for a failed filing.
- An hourly scheduled sweep that finds and retries failed till filings.
- A filing status on each sale, so the state is visible rather than inferred.
What it does not do
- Fiscal transmission to any authority outside Kenya. Not in West Africa, not in North Africa, not in Southern Africa, not in East Asia, not anywhere.
- Any filing at all while offline — the till requires a connection to sell, so the question does not arise in the way it would elsewhere.
- A reconciliation report of what was sold against what was successfully transmitted, over a period.
- Any pre-flight validation that a sale will be accepted before it is attempted.
Not ours, by choice
- The one fiscal integration in this product exists because Kenyan clients commissioned it. That is the honest reason, and it is also the reason the same door is open elsewhere.
- The docblock incident is published because the failure mode generalises: a comment copied between two similar flows describes a control that exists in one of them, and no test catches a comment.
- Nothing here is Korean, and no claim is made about any East Asian filing obligation. Korea is here as a mature card-and-receipt retail market where the counter is expected to be fast and correct.
What is not built today can still be built for you
Anything described above as not built is a statement about what ships in the standard product today — not a limit on what AWRA OpsHub can do for your organisation. Kenya's eTIMS integration and its maintained payroll engine are both in the product because clients needed them and commissioned them; neither appeared by itself, and the same door is open for the gap you just read about. Two honest qualifications so this is worth what it claims: a handful of gaps on this blog are deliberate refusals rather than missing work — a statutory ledger we will not sign our name to, a rule that would decide a tax question for you, a clinical or member-funds record that belongs in a regulated system — and where that is true the post says so in those words rather than calling it a gap. Everything else is a scope, a timeline and a price.
The operational work, which is what most commissions actually are
An extra approval stage in a chain that does not match the standard one, a custom field set on employees or assets that only your sector needs, an expiry that has to block an order rather than send an email, a report your board asks for in a shape nothing produces, or a scanner or weighbridge feeding the goods-in door. These are the commissions we are asked for most often and the smallest ones we quote — and unlike a revenue-authority pipeline, none of them waits on a regulator.
The module-shaped gaps, which are the ones this blog admits most often
A price list with real discount authority, a customer-facing quotation that expires, a bill of materials or recipe costing, a staff advance that is issued, acquitted and chased, a member or unit ledger, a matching rule that holds a payment. Each of these is a build rather than a setting, and each has been quoted before — a bigger piece of work than a custom field, with a written spec and a date instead of a roadmap slide.
The report, document or pack nothing currently produces
The board pack in the shape your board actually asks for, a donor or funder layout, an invoice or receipt template carrying what your regulator or your customer expects, a dataset the report builder cannot reach yet. Usually the fastest thing on this list to deliver, because the data is already in the system.
Systems, rails and hardware you already run
The accounting package, CRM, online store, core banking or custom database you intend to keep — connected through our API so a fact is entered once and appears everywhere it is needed. Plus the physical edge: a scanner, a scale, a weighbridge or a till peripheral feeding the door it belongs to.
How it works: you describe the requirement, we return a written scope, timeline and cost, and once agreed it is built into your environment and maintained as part of the product. Nothing here waits on a regulator or a published specification, which is why operational builds are the ones we quote fastest. Tell us the requirement that would otherwise rule us out — that is a better first conversation than a demo.
Tell us what your operation needsFour questions about anything that files on your behalf
What happens when a filing fails?
A good answer sounds like
Retries, then a sweep, then a person.
What it actually means
Three layers. Ours had one and a comment claiming two.
How would I know a filing had failed?
A good answer sounds like
A status, and something that tells me.
What it actually means
A status nobody looks at is not a notification. The sale looks perfect at the counter either way.
Can I retry one deliberately?
A good answer sounds like
Yes, from the sale.
What it actually means
Without it, fixing the underlying problem does not fix the backlog it created.
Show me sales not transmitted this month.
A good answer sounds like
A filter or a report.
What it actually means
This is the reconciliation that closes the loop, and it is the one we still do not have.
Our position
Where the software files on your behalf, ask what happens on failure and ask to see the failed list. A filing pipeline without a recovery path is not broken until the day it is, and it fails in the direction that produces no symptom at the counter. We had one, our own comment said we did not, and it took an audit rather than a customer to find it.
Ask to see the failures
Not the success path — the failure list. Every integration has one, and whether a vendor can show it to you in ten seconds tells you how much thought went into the day it matters.
Talk about fiscal integrationsFrequently asked questions
Does the till file to a tax authority in my country?
Only in Kenya. There is one fiscal integration in this product and it transmits to one authority; everywhere else, a sale is a sale in the system and whatever your local obligation is remains yours to meet by other means.
Could a filing failure stop the shop selling?
No, and deliberately. The filing is queued after the sale is committed precisely so that a slow or unavailable authority endpoint can never prevent a transaction at the counter.
How did a wrong comment survive review?
Because it was accurate about the flow it was copied from and plausible about the one it landed in. Tests exercise code; nothing exercises a paragraph. The best defence found so far is recording the correction rather than quietly editing it, so the next copy is less likely.
