Langs de voordeur: waarom onze eigen garagesoftware Konvoi als een vreemde behandelt

De shortcut lag binnen handbereik

Toen we begonnen aan Konvoi Workshop, de garagesoftware voor transportbedrijven met een eigen werkplaats, lag elke shortcut binnen handbereik.

Dezelfde repository als Konvoi. Hetzelfde team. Dezelfde databaseserver. Konvoi kent elke truck al, zijn nummerplaat, zijn vlootnummer, zijn kilometers en de schade die een chauffeur vanochtend meldde. Workshop heeft dat allemaal nodig. De snelste weg ernaartoe was één query.

Wij schreven het omgekeerde in de eerste regel van het plan:

Konvoi Workshop praat met Konvoi enkel via de publieke Partner API en webhooks, precies zoals elke andere werkplaatssoftware dat zou doen.

Geen gedeelde database. Geen interne endpoints. Geen hulpfunctie uit de code van Konvoi importeren omdat die toevallig één map verder staat.

Waarom het moeilijker maken

Omdat de meeste van onze klanten onze garagesoftware nooit zullen gebruiken.

Een transportbedrijf met een eigen werkplaats heeft meestal al een werkplaatspakket, en dat al jaren. Konvoi moet daarmee koppelen. Die koppeling loopt via de Partner API, en een API is maar zo goed als het veeleisendste wat er ooit gebruik van maakte.

Had onze eigen Workshop een achterdeur gebruikt, dan was de voordeur nooit getest door iemand die ze echt nodig had. Elk ontbrekend veld was weggemoffeld met een snelle join, en het eerste externe werkplaatssysteem dat koppelde, had de gaten voor ons gevonden.

Dus werd Workshop bewust die veeleisende externe gebruiker.

De regel laten standhouden

Een regel in een plan houdt stand tot de eerste deadline. Dus deze wordt afgedwongen door de build:

• Workshop heeft een eigen database, en zijn configuratie weigert te starten op een database waarvan de naam niet “workshop” zegt.
• Een grenstest scant elke import in de Workshop-apps en faalt als er een in de code van Konvoi grijpt, via een pad of een pakketnaam. Hij controleert ook de andere richting: Konvoi mag Workshop niet importeren.
• Wat de twee delen, zit in pakketten die iedereen zou kunnen gebruiken: het designsysteem, de datagrid, en de rekenregels voor wanneer een onderhoudsplan vervalt.

De handige import staat nog altijd één regel verderop. Hij raakt alleen niet voorbij de CI.

Het gatenlogboek is de spec

Het interessante deel is wat er gebeurt als Workshop iets nodig heeft dat de API niet biedt.

De regel zegt: schrijf het op, en los het op in de publieke API. Niet in een privé-endpoint voor Workshop, niet via een zijkanaal. Elk gat gaat in één logboek, wordt opgelost waar elke partner het kan gebruiken, en wordt doorstreept.

Zodra Workshop live is, is dat logboek de integratiespec voor elk ander systeem. Het is een lijst van precies wat een garage nodig heeft van een vlootplatform, ontdekt door er een te bouwen, niet door te gissen in een vergadering.

Een klein voorbeeld van hoe dat in de praktijk voelt: een voertuig dat in Konvoi aangepast wordt, bereikt Workshop via een webhook in ongeveer tien seconden, en een afstemming vangt op wat een webhook miste. Dat werkt voor Workshop omdat het voor iedereen werkt.

Waar een herstelling vandaan komt

De twee producten uit elkaar houden, dwong ons om precies te zijn over iets wat vloten voortdurend fout doen: wat een herstelling kost.

Een onderdeel in het rek is stock, geen herstelling. Het wordt pas de kost van een truck als het op een werkorder gaat.

Er zijn er twee soorten. Een herstelling door een externe garage wordt aangemaakt uit de factuur van die garage, die Konvoi al leest. Een herstelling in je eigen werkplaats wordt aangemaakt door de werkplaatssoftware, met de gewerkte uren en de onderdelen uit stock.

En de factuur van een onderdelenleverancier is geen van beide. Het is een stockaankoop. De kost komt pas bij een truck als het onderdeel op een werkorder uitgegeven wordt. Een factuur gekoppeld aan een herstelling is bewijs, nooit extra kost. Schrijf je het zo op, dan is dubbel tellen niet langer iets wat je controleert, maar iets wat niet kan gebeuren.

Stock is een grootboek

Hetzelfde denken ging naar het rek.

Stock in Workshop is nooit een getal dat iemand aanpast. Elke wijziging is een beweging in een grootboek waar enkel bij kan komen, geschreven in dezelfde transactie als de hoeveelheid, met de partijen die ze raakt vergrendeld. De database zelf weigert elke andere schrijfactie op de hoeveelheid, en weigert een beweging te wijzigen of te verwijderen. De voorraad kan altijd opnieuw opgebouwd worden uit het grootboek, en een nachtelijke controle bewijst dat dat kan.

De test die we vooraf vastlegden: twintig aanvragen voor de laatste anderhalve liter olie, allemaal op hetzelfde moment, brengen ze nooit onder nul, en de heropbouw uit het grootboek klopt nog altijd met wat in het rek staat.

Hoeveelheden en geld zijn decimalen van begin tot eind, nooit kommagetallen met afrondingsfouten. Een vat van 208 liter van een leverancier wordt via een factor omgerekend naar liters in stock, niet via afronden.

Slechte wifi is een vereiste

Een werkplaats is een metalen loods. De tablet naast de truck zal zijn verbinding verliezen, en hij zal opnieuw proberen.

Dus elke actie van de tablet draagt een id die de tablet zelf verzon, en de server past ze één keer toe. Alles wat Workshop naar Konvoi stuurt, gaat via een outbox en wordt opnieuw geprobeerd tot het aankomt. Een mecanicien die drie keer op “klaar” tikt over een haperende verbinding, werkt de taak één keer af.

AI stelt voor, mensen bevestigen

Een garage in nieuwe software krijgen, begint meestal met een week stocklijsten intypen. Workshop heeft een eigen MCP-server, dus een planner kan Claude of ChatGPT koppelen en de stocklijst, de vakcodes en de prijslijst van een leverancier geven zoals ze zijn.

De assistent leest ze en stelt een import voor. Een mens keurt die goed in Workshop. Niets wat de assistent voorstelt, verandert het rek tot iemand ja zegt.

Wat het kostte

Snelheid, soms. Meer dan eens wachtte een functie in Workshop omdat het veld dat ze nodig had eerst aan de publieke API van Konvoi toegevoegd moest worden, met documentatie, een rechtenscope en tests, in plaats van een query van twee regels.

We zouden dezelfde ruil opnieuw maken. Elk van die gaten is nu dicht voor elk systeem dat met Konvoi koppelt, en het product dat we bouwden om het te bewijzen, is een betere garagetool omdat het eerlijk gehouden werd.

Konvoi Workshop is live. Heb je een eigen garage, vertel ons hoe ze draait en we tonen je Workshop met jouw werkplaats erin.