The Shortcut Was Right There
When we started building Konvoi Workshop, the garage software for transport companies with their own workshop, every shortcut was within reach.
Same repository as Konvoi. Same team. Same database server. Konvoi already knows every truck, its plate, its fleet number, its kilometres and the damage a driver reported this morning. Workshop needs all of that. The quickest way to get it was a query away.
We wrote the opposite into the first line of the plan:
Konvoi Workshop talks to Konvoi only through the public Partner API and webhooks, exactly as any other workshop software would.
No shared database. No internal endpoints. No importing a helper from Konvoi’s code because it happens to be one folder over.
Why Make It Harder
Because most of our customers will never use our garage software.
A transport company with its own workshop usually already has a workshop package, and has had it for years. Konvoi has to connect to those. That connection runs through the Partner API, and an API is only as good as the most demanding thing that ever used it.
If our own Workshop had used a back door, the front door would never have been tested by anyone who really needed it. Every missing field would have been papered over by a quick join, and the first outside workshop system to connect would have found the holes for us.
So Workshop became that demanding outside user, on purpose.
Making the Rule Stick
A rule in a plan lasts until the first deadline. So this one is enforced by the build:
- Workshop has its own database, and its configuration refuses to start against a database whose name does not say “workshop”.
- A boundary test scans every import in the Workshop apps and fails if one reaches into Konvoi’s code, by path or by package name. It also checks the other direction: Konvoi may not import Workshop.
- What the two share sits in packages anyone could use: the design system, the data grid, and the arithmetic for when a maintenance plan is due.
The convenient import is still one line away. It just doesn’t get past CI.
The Gaps Log Is the Spec
The interesting part is what happens when Workshop needs something the API does not offer.
The rule says: write it down, and fix it in the public API. Not in a private endpoint for Workshop, not in a side channel. Every gap goes into one log, gets fixed where every partner can use it, and gets crossed off.
Once Workshop is live, that log is the integration spec for every other system. It is a list of exactly what a garage needs from a fleet platform, discovered by building one, not by guessing in a meeting.
A small example of how that feels in practice: a vehicle edited in Konvoi reaches Workshop by webhook in about ten seconds, and a reconcile catches whatever a webhook missed. That works for Workshop because it works for anyone.
Where a Repair Comes From
Keeping the two products apart forced us to be precise about something fleets get wrong all the time: what a repair costs.
A part on the shelf is stock, not a repair. It only becomes the cost of a truck when it goes onto a work order.
There are two kinds. A repair done by an outside garage is created from that garage’s invoice, which Konvoi already reads. A repair done in your own workshop is created by the workshop software, with the hours worked and the parts issued from stock.
And a parts supplier’s invoice is neither. It is a stock purchase. The cost reaches a truck only when the part is issued on a work order. An invoice linked to a repair is evidence, never extra cost. Write it down like that and double counting stops being something you check for and becomes something that cannot happen.
Stock Is a Ledger
The same thinking went into the shelf.
Stock in Workshop is never a number someone edits. Every change is a movement in an append-only ledger, written in the same transaction as the quantity, with the lots it touches locked. The database itself refuses any other write to the quantity and refuses to change or delete a movement. On-hand stock can always be rebuilt from the ledger, and a nightly check proves that it can.
The test we set before calling it done: twenty requests for the last litre and a half of oil, all at the same moment, never take it below zero, and the rebuild from the ledger still matches what is on the shelf.
Quantities and money are decimals end to end, never floating point. A 208-litre drum from a supplier converts to litres in stock through a factor, not through rounding.
Bad Wi-Fi Is a Requirement
A workshop is a metal shed. The tablet next to the truck will lose its connection, and it will retry.
So every action from the tablet carries an id the tablet made up itself, and the server applies it once. Everything Workshop sends to Konvoi goes through an outbox and is retried until it lands. A mechanic who taps “done” three times over a flaky connection finishes the job once.
AI Proposes, People Confirm
Getting a garage into new software usually starts with a week of typing stock lists. Workshop has its own MCP server, so a planner can connect Claude or ChatGPT and hand it the stock list, the bin codes and a supplier’s price list as they are.
The assistant reads them and proposes an import. A person approves it in Workshop. Nothing the assistant suggests changes the shelf until someone says yes.
What It Cost
Speed, sometimes. More than once a feature in Workshop waited because the field it needed had to be added to Konvoi’s public API first, with its documentation, its permission scope and its tests, instead of a two-line query.
We would make the same trade again. Every one of those gaps is now closed for every system that connects to Konvoi, and the product we built to prove it is a better garage tool for having been kept honest.
Konvoi Workshop is live. If you run your own garage, tell us how it works and we will show you Workshop with your workshop in it.