Inside Whstrace: how we built an EUDR compliance and traceability engine.

The engineering brief

We read the EU Deforestation Regulation as a list of things the software has to be able to show. Each duty became a requirement, and each requirement a part of the system.

Architecture

The back end is a NestJS service written in clean-architecture layers: framework-free domain entities, use cases written against ports, Prisma adapters, and a thin HTTP layer on top. Everything lives in one PostgreSQL database with the PostGIS extension. Boundaries, areas and overlaps are geographic questions, and the database answers them exactly, so there is no separate search or geographic service to keep in step.

• Admin console: Angular with standalone components and signals, with Mapbox maps for boundaries and verdicts.
• Field app: Flutter on Android, offline first, with local storage and a background sync engine.
• Photos and evidence: an S3-compatible private object store, so images and generated files never sit on a public path.
• Permissions: read from the code. Each protected route declares the permission it enforces, the list is synced into the database at boot, and a role can only be granted a permission that a real endpoint checks.
• One transaction per change: every write is paired with its audit entry in the same database transaction. Either both are saved or neither is.

The offline field app

The field is where the evidence is made, so the app was designed around the connection that exists there. Everything an officer records is written to the phone first. A sync engine then sends it in order, retrying with back-off, recovering after a crash and confirming each item against the server before it marks it as done.

Location capture, sync status per farmer and the final review. Fictional demonstration people.

Design decisions that carry the weight

• Stable client identifiers. Every record gets its identifier on the phone. A retried send carries the same identifier, so the server recognises it and updates the record it already holds.
• Ordered uploads. A farm photo waits until its parent farm has synced. Crops, trainings and challenges keep their entry identifiers across edits, so they stop duplicating.
• Reference data on demand. Locations, cooperatives and the questionnaire are downloaded at sign-in in parallel pages, sorted stably and compressed. Old questionnaire versions stay on the phone until their unsent answers are delivered.
• Access on the device. PIN or fingerprint unlocks the app offline, and officers are scoped on the server to the records they registered.
• Release management. The admin console reads each APK's manifest, tracks downloads and shows which build every officer last signed in with.

Choosing the geometry to check

The regulation asks for a polygon on plots above four hectares and allows a single point at four hectares or less. Field data does not always arrive in the shape the regulation prefers, so the engine applies one decision rule to every farm:

1. 01

   If the captured boundary is a valid polygon that covers at least half of the recorded area, the polygon is checked.

2. 02

   Otherwise the centre of the captured points is the legal location, and a circle of the recorded area is checked. When no believable area exists (the plausible range is 0.25 to 25 acres) the engine assumes one acre, the typical family plot.

3. 03

   A plot above four hectares without a usable polygon fails, because the regulation requires one.

A boundary that crosses itself is flagged for correction. A boundary is rechecked whenever it changes, and exported with six decimal places in WGS84.

The compliance engine

The engine asks five independent sources about each plot and keeps every answer.

• Global Forest Watch: forest cover in 2020 from the JRC dataset, tree-cover loss since 2021 from the University of Maryland and integrated deforestation alerts.
• FAO Whisp: an independent risk rating, kept as a second opinion.
• Copernicus Sentinel-2: satellite imagery of the farm on request, stored with the assessment as visual evidence.
• OpenStreetMap: protected areas, with their IUCN class.
• Our own farm data: the boundaries of neighbouring plots, for the overlap test.

The rules are plain functions in a single file. Every assessment stores the rules version that produced it, currently eudr-2026.3, so any verdict can be traced to the exact rules behind it, and a rule change creates a new version without touching past results.

Two small rules keep the output honest. A signal below 0.01 hectare, about a tenth of a satellite pixel, counts as noise. The Whisp opinion is flagged only when it rates cocoa risk high while our own checks found nothing, because the reverse case is expected: our checks also cover protected areas and the four hectare rule.

Running at scale

Checking thousands of farms against rate-limited public services is a scheduling problem. Checks wait in a queue inside the database, and several processes can share it safely because each check is claimed exclusively.

Concurrency

Up to 12 checks run at once. A failed check is retried up to five times with back-off.

Crash recovery

A check left running by a crash returns to the queue after 15 minutes.

Quota awareness

The forest service allows 10,000 requests a day. When it is spent, the queue pauses for an hour and the affected checks keep their place without using a retry.

Nightly re-checks

After 01:00 Kampala time, farms never assessed or last assessed 120 days ago are queued. An assessed farm stays locked until its boundary changes.

Satellite imagery draws on a monthly allowance. The engine refuses a request that would spend the last five percent and reuses images it already holds.

Integrity by design

A compliance record is only worth keeping if nobody can quietly change it. The audit log is protected by the database itself:

entry.hash = sha256( entry.content + previous_entry.hash )

writers      serialised with a database lock
UPDATE       refused by trigger, for every account
DELETE       refused by trigger, for every account
TRUNCATE     refused by trigger, for every account
verify()     recomputes the chain, reports the first break

Verdicts add a second layer. Each is stored with its evidence and a SHA-256 fingerprint, and a later assessment adds a new record without overwriting the earlier one.

People stay in the loop

An automated check can flag a problem, and a person decides what it means. Records that need a decision wait in a data review queue with seven kinds of finding, including EUDR compliance findings, possible duplicate people, values that do not fit the current rules and legality documents about to expire.

• Legality documents need a second person to verify them (four eyes), and the system warns before a verified document expires.
• A risk assessment is built from seven criteria: country, deforestation, protected areas, the second opinion, land tenure, open findings and supply chain. A named person signs it off and can attach mitigation steps.

The due diligence package

Deliveries are graded into lots to ISO 2451. The weights must balance exactly, so no cocoa disappears, and a lot never mixes eligible and non-eligible cocoa. A lot carries every farm behind it in proportion. From there the platform builds a package for the buyer: the geolocation as a GeoJSON feature collection in WGS84, the verdicts, the evidence, the receipts and the statement reference recorded from TRACES. Packages are immutable and carry their own checksums, one per lot and one combined per order.

What went wrong, and what we changed

The first version of the system was used in the field long before this one existed, and it taught us most of what the current design does. A short list of the problems and their fixes:

Records from the first version were reviewed for duplicates, test entries and invalid values, then imported through a staged process with reconciliation, and the audit chain was verified after the move. Demonstration data is separate: the screenshots in this release come from a fictional database, so no real farmer appears in them.

Limits we state openly

• Resolution. The satellite datasets work at about 30 metre pixels, so very small clearings and shaded tree crops can be missed or misread.
• Points for small plots. Where a farm has only a point, the engine checks a circle. That meets the regulation up to four hectares but estimates the real shape, and a walked boundary remains the better evidence.
• Our reading of the rules. The rules are versioned so they can follow the regulation. The platform supports due diligence and leaves the operator's legal responsibility where it is.
• Documents and platforms. The system records legality documents and who verified them, and cannot confirm that a document is genuine. The field app runs on Android only.

Hopes and future plans

Cocoa came first, and the engine was built so that the crop is a setting and the machinery stays the same. Plots, boundaries, versioned questionnaires, versioned rules, the sync engine, the audit chain and the package export do not depend on cocoa. What changes from crop to crop is smaller: the questions, the quality grading, the rule thresholds and the regulatory detail.

Other crops the regulation covers

The regulation names cattle, cocoa, coffee, oil palm, rubber, soya and wood. Leaving coffee aside, this is how we see the remaining ones, from the least to the most new work.

• Soya

  Large and mid-sized plots make polygons the normal case. The boundary rules, satellite checks and package export apply unchanged. The questionnaire and the grading step change.

• Oil palm

  Plantations and outgrower schemes map well onto cooperatives with members and plots. Peat and protected-area overlaps become more important, and the rule set gets a new version for them.

• Rubber

  Smallholder rubber fits the same registration and mapping flow. Rubber has a long tree-crop cycle, so the forest baseline question carries more weight than it does for annual crops.

• Wood and cattle

  Both are in the regulation. Wood needs harvest-area and species records on top of the plot, and cattle need records of the animals and of every establishment they passed through. These are the largest changes to the data model.

Chilli and crops outside the regulation

Chilli is outside the regulation today, so it carries no deforestation duty. Export buyers still ask where a crop was grown and how, and a cooperative that can answer with mapped plots and recorded practices has an advantage over one that cannot. The farm questionnaire already records pest management plans, pesticides used, biological control and integrated pest management practices, which is the information those buyers ask for. For chilli and similar export crops, the same registry, boundary capture, questionnaire and lot records give a cooperative an origin story it can show, without the satellite rules becoming a legal requirement.

What we plan to work on

1. 01

   Commodity packs. A crop becomes a bundle of questionnaire, rules version and grading standard that can be switched on per cooperative.

2. 02

   Better evidence for small plots. Walked boundaries for every plot, so the circle estimate is used less and less.

3. 03

   Following the regulation. New rule versions as the guidance changes, with the old ones kept so past verdicts stay explainable.

4. 04

   Verified lots for buyers. Publishing graded lots in the online shop, each with the proof behind it.

5. 05

   More cooperatives, more officers. Each mapping round with a new team teaches us something about the field app, and we plan to keep acting on it.

Our hope is simple. A smallholder anywhere on the regulation's list should be able to prove where a crop grew without hiring a consultant, and a cooperative should hold that proof itself.