Skip to content
Junaid Gool layer markJunaid Gool.
Back to work
Case study

Tycho

Someone applies for finance and hands over a payslip and a bank statement. Are the documents real? Tycho reads each one into typed records, runs 7 independent checks over it, and returns one of 4 verdicts with every reason written down, so a person can read the reasoning and disagree with it.

.NET 10PostgreSQLAzurePdfPigML.NETVue 3
7
Detection layers
4
Verdicts
8
Services
The Tycho sign-in screen: a single red lens above the Tycho wordmark, the words document verification beneath it, and one sign-in button.
Sign-in. The whole brand mark is one lens, drawn in CSS. Design mockup: every name and figure in these screens is fictional.
intake-apiscan · SHA-256 · queueBlob storageoriginal, stored once by hashnever modifiedenqueue1 Triagepipeline-svc2 Forensicsforensics-svc3 Classifyextraction-svc4 Extractextraction-svc5 Authenticityauthenticity-svc6 Scorescoring-svc7 Finalisepipeline-svcclaim work · commit result, events, and the next step in one transactionPostgreSQL – the spinejob queue (SKIP LOCKED + lease) · append-only event log · verdicts · settings snapshotsreview-apiqueue · evidencewebVue 3, 6 screensAnalyst decisiona new verdict, supersedes
Seven stages across five processing services. They never call each other: each writes what it concluded to the spine, and the next one reads it back.

Overview

The product a person signs into is called Tycho. Everything technical keeps the system name: the repository, the services, the schemas, and the contracts. A product name is what a person reads, and a system name is what an operator greps for at 2am, so renaming the second to match the first would be churn with nobody on the other end of it.

The documents are South African, so the checks are too: payslips tested against the SARS tax tables and the UIF ceiling, statements tested line by line against their own running balance, and ID numbers and bank branch codes tested against the check digits built into them.

Most verification systems answer pass or fail. The dangerous case is the one in between: a document the system could not read properly. Without care, "I checked nothing" comes back looking exactly like "I found nothing", and that is how a forgery gets cleared quietly. So there are 4 verdicts rather than 2. Authentic clears. Fraudulent refuses. Suspicious goes to a person. Unverifiable also goes to a person, and it exists so an unreadable document can never fall through to Authentic.

The system may only condemn a document using values it read clearly. If it could not read clearly, the answer is Unverifiable and a person looks. An unclear document is never quietly cleared.
Status
In progress, and honest about it. The architecture and the service specifications are complete, and the pipeline runs end to end in a development environment – a genuine payslip came back Authentic, and a retyped tamper came back Fraudulent. It has not yet been measured against a full corpus of real documents, hardened, or piloted. The accuracy numbers are not in, so there are none on this page.

Seven ways to look at one document

No single check is the fraud detector. Each layer looks at the document a different way, and no check depends on another, so a forger who beats one has not touched the rest. The weights are sized so that no single layer can cross the review threshold on its own.

  • Structure – what the file says about itself. A PDF is a database of objects with a history. Two independent parsers read it, and if they disagree about the structure, the disagreement is itself evidence.
  • Typography – a digital PDF stores the exact position of every letter as numbers, so the check measures coordinates rather than pixels: baselines, letter spacing, a font that switches in the middle of an amount, and anything painted on top of existing text.
  • Pixels – render the page, read the image back with OCR, and compare it against the text stored inside the file. Lines are matched by their position, not their content, because an edited line is the one that least resembles its replacement.
  • Numbers – gross minus deductions equals net, to the cent. Previous balance plus transaction equals new balance, on every line. PAYE against the tax tables, and UIF against its legal maximum.
  • Cross-document – does the story hold together within one submission, across months, and across everything ever submitted. Because every file is stored under its fingerprint, the same statement appearing under 2 different applicants is a single lookup.
  • Issuer – every other layer infers, this one proves. Some banks publish a way to ask them directly, through a code printed on the statement or a public verification page. The answer is confirmed, refuted, or unavailable, and unavailable is shown as not checked rather than as a pass.
  • Anomaly – a small model trained on genuine documents only, running locally. It is advisory: it can push a document toward review, and it can never raise a fraud flag or be the only reason a document is refused.

Revision archaeology

A PDF can be saved with incremental updates, where the edit is appended and the original stays inside the file. When that history is there, the system does not stop at "this was edited". Each saved revision is a complete snapshot, so it opens every revision and compares them. The finding is not that something changed. It is that the net pay was edited, with the exact box on the page it happened in.

How a verdict is decided

Every rule that fires feeds one of two channels. Weak signals add points to a score, because one odd thing is life and three odd things are a pattern. Conclusive findings raise a flag instead, and a flag does not need help from anything else.

A flag is only as good as the reading underneath it. If the net pay that failed arithmetic was read from a blurry photo, the honest conclusion is that the OCR may have misread it, not that the document is forged. So a flag only stands if every value it rests on was read at 0.90 confidence or above. Below that, the flag is stripped, the strip is recorded, and the verdict is forced to Unverifiable. It can never fall through to Authentic – the system has just objected to the document, and it must not clear it in the same breath.

nononoyesyesyesyesnoAny fraud flag standing?conclusive on its ownAny flag stripped?it rested on a value read below 0.90Essential fields unreadable?net pay, balancesScore over 50, or a rule crashed?small suspicions add upFraudulentrefusedUnverifiablea person looks · never clearedSuspiciousa person looksAuthenticcleared
Order matters: proof beats suspicion, and honesty about what could not be read beats both.

Two more rules close the obvious gaps. A rule that crashed checked nothing, so a crash makes the document Suspicious rather than passing in silence. And unreadable essential fields are a finding in themselves, which shuts the loophole where someone submits a deliberately poor photo hoping every arithmetic check politely skips.

What the analyst sees

A finding means nothing until you can look at the document, so the review screen puts the two side by side. Every finding names its rule, says its reason in a plain sentence, and carries the exact box on the page it came from. The checks that did not run are listed too, in their own panel, because a check that did not run is not a check that passed.

The Tycho review screen: a payslip on the left with the net pay figure boxed in red, and a findings panel on the right listing the arithmetic failure, the revision edit over the net pay field, a font run change, a PAYE plausibility check, a cross-document mismatch, and a panel of checks that did not run.
The review screen. The arithmetic fails, revision 2 replaced the objects sitting on the net pay field, and the digits are set in a different font subset to the rest of the page. Design mockup, fictional data.

The queue is oldest first, always, with no re-sorting by score. The risk in a review queue is the document quietly ageing at the bottom, not the one that just arrived. Every row carries its full reason, so nobody has to open a document just to find out why it is waiting.

The Tycho review queue: five documents with verdict badges reading Fraudulent, Suspicious, and Unverifiable, each row showing the full reason it is waiting.
The queue, oldest first. Each row says what objected and with what numbers. Design mockup, fictional data.
Colour never carries it alone
Each verdict has its own colour, and Unverifiable sits deliberately outside the other three, because "I could not tell" is not a decision and must not borrow the look of one. No colour ever carries the meaning by itself: every badge pairs its hue with an icon and the word, and the boxes drawn on the document differ by border style too, solid for conclusive and dashed for suspicious. The meaning has to survive colour blindness and a greyscale printout.

The engineering

It is 8 services: 2 edge APIs, 5 processing workers, and the web app the analysts use. They never call each other. They meet at one PostgreSQL database that holds the job queue, the event log, the verdicts, and the rule settings.

The queue lives in that same database on purpose. A worker claims a step with SKIP LOCKED under a lease it heartbeats, does the slow work outside any transaction, then commits the result, the events it appended, and the enqueue of the next step together. All of it happens or none of it does. A reaper requeues anything whose lease expired, so a worker dying mid-document does not strand that document.

Nothing is edited
The original file is stored once, named by its SHA-256 fingerprint, and only ever read. Every step appends what it concluded to a log that is never rewritten. A verdict is never edited either: an analyst decision is a new verdict that supersedes the old one, and both stay readable with who decided and why. Clearing a document the pipeline objected to needs a written note, because that is the judgement that needs explaining. Confirming fraud does not, because the evidence is already on record.

Every verdict also stores the exact rule weights that produced it, so any verdict can be explained and reproduced months later rather than reconstructed from memory. The 34 catalogued rules are data rather than code, which means the February change to the SARS tax tables is a settings update and not a software release.

What I deliberately left out

There is no message broker. Keeping the queue inside PostgreSQL is what lets "finish this job, save the result, start the next one" be a single transaction, which a separate broker cannot promise and which adds a whole new thing that can fail. There is no cache tier and no service mesh, for the same reason: every extra part is an extra failure.

There is also no large language model. No document data is ever sent to a chat model, which keeps privacy simple and keeps every verdict explainable to the person who has to defend it. The only machine learning is the small local anomaly model, and it can suggest review but never condemn.

The limits, stated up front

Re-exporting a document rewrites it from scratch. Sharing a statement from a banking app or printing it to PDF destroys the revision history, the original producer, and the original fonts. The structure layer is therefore silent on documents that took that route, which is the common one, and someone can take that route deliberately. So a silent structure layer is never read as a clean one. On those files the weight falls on the layers a re-render cannot launder: the arithmetic, the cross-document story, and the issuer's own answer.

The classic image checks are held back for a related reason. On a genuine payslip, the cloned-region check reported 18 duplicated regions. A check that accuses honest documents is worse than no check, so each one stays advisory until its false-alarm rate has been measured on real documents. Evidence first, then switched on.

Privacy by construction

POPIA is mapped condition by condition to a control that lives somewhere specific in the system rather than in a policy document. All processing and storage stays in one South African region, enforced with an outbound allow-list rather than stated as an intention. No data store faces the internet. Retention is tiered to what the law requires, and a document that has not been classified takes the longer tier on purpose.

Back to
Selected work
→