A legal obligation that everybody satisfied with small print, rebuilt as the strongest part of the sale

Overview

Legally sufficient, commercially worthless. We built the system that answers the real question.

In several jurisdictions a specialist retailer must tell the customer exactly where an animal came from: the breeder's name, their national licence number, and their inspection record. Almost every store satisfies this with a line of small print on page four of a contract.

That is legally sufficient and commercially worthless. It answers a regulator's question and ignores the customer's. The customer is not asking for a licence number. They are asking is this a good place, and can I see it?, and they are asking it at the exact moment they are deciding whether to buy.

We built the system that answers the real question: a proper supplier profile with photographs, video, the parent animals, accreditation marks and the actual government inspection reports, readable in the page. A salesperson can bring it up on a tablet mid-conversation without breaking the conversation to log in.

The challenges

Five problems between satisfying the law and winning the customer's trust.

Compliance was being met, and reassuring nobody

A national licence number printed in a contract is a string of digits. It proves a record exists somewhere. It shows the customer nothing and reassures them of nothing. Because it appears in the small print of a legal document, it actively signals that it is something to be got past rather than something to be proud of.

The information that would genuinely reassure a buyer already existed. It was just being presented in the one format guaranteed to have no effect.

Inspection reports are scanned PDFs, and a PDF ends the conversation

The official reports exist as scanned documents. Linking to one means asking a customer to download a file, on store wifi, on their own phone, while a salesperson stands waiting.

Whatever happens after that, it is not a sale. The customer looks down, the moment breaks, and the thing meant to build confidence has instead introduced a pause and a loading bar.

Several stores share the same suppliers, but must not share the same voice

The same breeders supply multiple partner stores. Giving each store its own copy of each supplier's profile means the same facts maintained many times over, drifting out of date at different speeds: the licence number correct in one store's copy and stale in another.

But a single shared profile forces every store to describe that supplier in identical words, which strips out exactly the thing a store's own customers respond to.

Logging in in front of a customer is its own problem

A salesperson holding a tablet cannot stop to type a username and password in front of the person they are selling to. It is slow, it looks unprofessional, and it exposes credentials in a room full of strangers.

An open system with no login is not an option either. This is supplier data across competing stores, and every action needs to be attributable to a real member of staff.

Not every supplier is licensed the same way, and staff must not have to know

Larger breeders hold a national licence and are inspected under it. Smaller independent breeders do not, and have a different kind of record entirely.

Showing a regulator-inspection section for a breeder who has none looks like something is being hidden.

Expecting a salesperson to know which disclosure applies to which supplier, correctly, every time, in front of a customer, is a bad plan that eventually produces a bad outcome.

On the shop floor · the token hand-off

The password you cannot type in front of a customer

A salesperson is mid-conversation. The customer has just asked the question that decides the sale: where did this animal actually come from?

The right answer is to hand them a tablet showing the breeder's facility, their licence and their inspection report. The wrong answer is to say "one moment", turn the tablet away, and type a username and password while the customer watches.

So we removed the login from the shop floor entirely.

The salesperson is already signed in to their own store's system, properly, with their own credentials, at the start of their shift. When they tap through to a supplier profile, that system quietly creates a fresh session record in the transparency platform behind the scenes: which store, which member of staff, their name, a generated token, and the time.

The tablet then opens a link carrying that token. The platform recognises it, knows exactly which member of staff at which store is holding the device, and opens the supplier search already signed in.

The result

Nothing is typed. Nothing is shared. Nothing is anonymous.

The easy version of this problem has an easy and terrible solution.

This matters more than it first appears. The easy solution is a shared account with a password on a sticky note. That is what most stores end up with, and it destroys the audit trail, survives staff leaving, and spreads.

The token approach gives the opposite of all three

• The identity is real, so every action is attributable to a named individual.
• A fresh token is minted for every hand-off, so no secret is ever reused across staff or shared between devices.
• The customer sees none of it. From their side, the salesperson simply tapped a link and the facility appeared.

What we built

Five decisions that turned a disclosure into a profile worth looking at.

Chapter one · The profile

The profile a customer would actually want to look at

Each supplier profile carries the facility name, national licence number, regional licence number, full address, a written biography, photographs of the facility, pictures of the parent animals, and video, either uploaded directly or embedded.

The accreditation bodies they belong to are shown as recognisable marks rather than acronyms: a national industry body, two registries, the national animal health authority and the regional agriculture regulator, plus a separate mark for licensed mobile facilities. A customer who recognises one of those marks gets reassurance instantly, without reading anything.

Chapter two · Inspection reports

The inspection reports, solved by not being PDFs

This was the decisive problem, and the solution is not subtle.

When a store uploads an inspection report, the platform converts it into images immediately: page by page, at full quality, the moment it arrives. Each page is watermarked with the platform's mark, and the set is stored against the document.

The report then appears on the profile like any other photograph. The customer scrolls. Nothing downloads, nothing opens in another app, nothing takes them out of the conversation. The work happens once, at upload, on our servers, rather than every time a customer looks, on whatever phone or tablet happens to be in the room.

Chapter three · Shared record, per-store voice

One record of fact, many layers of voice

The tension between shared and individual was solved with a layer rather than a fork.

One supplier record holds the facts: licence numbers, address, inspections. It is maintained once, and correct everywhere by definition.

On top of it, each store writes its own words. Seven content blocks across the profile can be written per store, positioned where that store wants them. Each block is tagged with the stores it belongs to, so a supplier's profile reads differently, in the store's own voice and with the store's own emphasis, while the licence number underneath is the same single record.

The blocks also support automatic substitution of the breeder's name, so a store writes its wording once as a template and it reads naturally on every supplier it is applied to.

The seven blocks a store can write

• Regional oversight
• Licensed inspections
• Independent-breeder inspections
• Regional licensing and inspection
• Licensed mobile facilities
• Registration paperwork · two blocks

Chapter four · Licensing branch

The licensing branch staff never have to think about

The profile decides for itself. When a national licence number is present, it shows the licensed marks and the licensed inspection records. When there is none, it shows the independent-breeder inspection section instead, with its own store-written explanation.

The salesperson never chooses. There is no dropdown to get wrong, and there is no scenario in which a customer sees an empty inspections panel and draws the obvious conclusion.

Chapter five · Admin

Built so staff run it, not us

48 distinct admin actions exist so the people who use this system maintain it themselves.

Adding a supplier is a routine afternoon task for an administrator. It has never required us.

What staff manage themselves

• Adding suppliers
• Supplier details
• Inspection records
• Images and documents
• Per-store content blocks
• Brokers
• Stores
• Staff accounts
• User roles
• Per-page access
• Notification recipients

Technical deep-dive · the document pipeline

Inside the document pipeline, from a scan to a scroll

The single most valuable thing on a supplier profile is the official inspection report, and it arrives in the least usable format imaginable: a scan of a piece of paper, produced by a government process that never imagined a customer reading it in a store.

The obvious approach is to link to it. We rejected that, because a link is a download, a download is another app, and another app is the end of the conversation.

The second obvious approach is to render it in the browser. We rejected that too. It means shipping a document viewer to every device, and it means a five-year-old tablet on store wifi doing the work at the exact moment the customer is watching. The performance is unpredictable precisely when predictability matters most.

So the work was moved to upload time, and it happens once.

When an administrator uploads a report, the platform opens it, counts its pages, and renders every page as a separate image at full compression quality. Each image then passes through a watermarking step that composites the platform's mark onto it at a fixed offset from the corner. The finished set is recorded against that document, so the profile knows which images make up which report.

Three consequences, in order of how much they matter

• The customer's device does nothing unusual. It displays images. Every phone and tablet in every store already does this perfectly, and it is as fast as the rest of the page.
• The document cannot be quietly detached from its source. A watermarked page that circulates still carries its origin. For a document whose entire purpose is to prove provenance, that is the point rather than a decoration.
• The cost is paid once, by us, not repeatedly, by them. Rendering happens on our servers at upload. A report looked at ten thousand times is rendered once.

And deletion is handled as carefully as creation.

Removing a document removes its rendered pages too. A system that generates derived files and forgets about them leaves the customer-facing profile showing pages of a report that has been withdrawn. In a compliance product, a stale document is worse than a missing one.

How we work

Eight rules, built around how people actually sell.

Start from the conversation, not the statute

We began with what a salesperson needs at the counter and worked backwards to the legal requirement, rather than reading the regulation and producing something that satisfies it. Both approaches are compliant. Only one of them sells.

Design out every step that breaks the moment

Downloads, logins, loading screens, app switches. Each was identified as a conversation-killer and removed before the feature around it was built.

Separate fact from voice

Licence numbers are facts: stored once, maintained once, correct everywhere. Descriptions are marketing, and they belong to each store. Conflating the two is what forces the choice between stale data and identical copy, and it is a false choice.

Never make staff the safety mechanism

The independent-versus-licensed branch is decided by the data, not by a salesperson under pressure remembering which disclosure applies. Anything a person must get right every time in front of a customer will eventually be got wrong.

Do the expensive work once, on our servers

Documents are rendered at upload rather than on display. The shop floor gets predictable performance on old hardware, which is the only kind of performance that matters there.

Build for the slowest device in the building

A shop-floor tablet on the store's own wifi, not a developer's laptop on fibre.

Authenticate without interrupting

Real identity, full audit trail, nothing typed in front of a customer. The alternative that stores reach for by themselves is a shared password, and it is worse in every way.

Hand over the keys

Forty-eight admin actions exist so the client's own staff run this system day to day. A compliance product that needs a developer to add a supplier is a product that stops being accurate.

Technologies used

Eight layers, and what each one is for.

Platform

The public profiles and the admin system. 20 routes, 19 controllers.

• PHP
• FastRoute

Document rendering

Converts scanned inspection reports into scrollable images at upload.

• Spatie PDF-to-Image
• Imagick

Watermarking

Stamps every rendered page so it carries its origin wherever it travels.

• PHP image compositing

Data

One supplier record, with per-store content blocks layered on top.

• MySQL

Shop-floor access

Signs staff in from their own store's system with nothing typed.

• Per-hand-off session tokens

Permissions

Controls who can edit suppliers, stores, staff and page content.

• Per-store, per-role page access

Alerts

The right people are told when records change.

• Action-triggered email
• Configurable recipients

Admin surface

Staff maintain suppliers, documents, images and store wording without us.

• 48 admin actions

Automated testing

Automated tests check each change before it reaches production.

How the platform works

Six steps, from head office to the shop floor.

Step 1

Head office adds a supplier

Facility name, national and regional licence numbers, address, biography, photographs, parent pictures and video.

Step 2

Reports are uploaded as scans

The platform immediately renders every page as a watermarked image and records the set against the document. Nothing is left as a PDF for a customer to download.

Step 3

Each store writes its own wording

Seven content blocks across the profile, tagged to that store, positioned where the store wants them, with the supplier's name substituted automatically.

Step 4

The profile decides the disclosure

A national licence present means licensed marks and licensed inspections. Absent means the independent-breeder section instead. Staff never choose.

Step 5

On the shop floor

The salesperson taps through from their own system. A freshly generated token is written behind the scenes, and the supplier search opens already signed in, attributed to them by name.

Step 6

The customer sees the facility

Photographs, video, the parent animals, accreditation marks, and the real inspection report scrolling in the page like any other image.

Results

What the business can do now that it couldn't before.

Turn the legal minimum into the best part of the pitch

A licence number became a facility the customer can see, with the inspection report attached.

Answer the question that actually decides the sale

At the moment it is asked, without leaving the conversation.

Keep one supplier record across every partner store

Facts are maintained once, and each store's own voice is layered on top through seven per-store content blocks.

Show inspection reports in the page

No download, no second app, no loading bar at the decisive moment.

Open it on a tablet without typing a password in front of a customer

And still know exactly which named member of staff is holding it.

Handle licensed and independent suppliers correctly, automatically

No dropdown to get wrong, and no empty panel inviting the worst interpretation.

Prove where a document came from

Every rendered page carries a watermark.

Run it without us

48 admin actions, and adding a supplier is an afternoon's administration.

The engineering, in numbers

• 1 Supplier record per profile, shared across all stores
• 7 Per-store content blocks on a profile
• 5 Accreditation marks displayed, plus a mobile-facility mark
• 48 Admin actions available to staff
• 20 Application routes
• 19 Controllers
• 0 Passwords typed on the shop floor
• 100% Document conversion quality setting

Honest status

This system has a long history. Its files date back to 2016, and it has been maintained rather than rebuilt. This page describes a system we built and maintain, not a new product.

The code described here is a snapshot: its newest file dates to December 2021, just under five years before we reviewed it for this page. It was built on a custom PHP stack whose runtime is now long past end-of-life.

"Facts maintained once" refers to the supplier record, which is single and shared. Licence numbers are entered by administrators; the platform does not check them against any government register.

Related work

All work

Next step

Have a legal obligation that is still just small print?

Work with an engineering team that starts from the conversation, not the statute, designs out every step that breaks the moment, and hands your staff the keys.

Book a discovery call