A new engineer joins a platform with five product lines, roughly 150 supplier codes running on about 90 distinct integrations, and asks the reasonable question: where do I start reading. The honest answer is that reading is not the bottleneck and a month of it would not fix anything, because nobody learns ninety of anything. What people actually learn is one shape, and then the exceptions to it.
That is not a motivational point. It is the reason the architecture looks the way it does, and it means the parts that make the system tractable to operate are the same parts that make it learnable.
The shape, then the exceptions
Every supplier gets exactly one module, written against a fixed contract, and registered by its code in a single registry. Learn one module and you have learned the frame all ninety sit in: what the platform will call, in what order, and what shape it expects back. The differences between suppliers are not scattered through shared code — that is the whole point of the contract — so they can be met one at a time, when a ticket makes them relevant.
Then the exceptions, and there are precisely two worth teaching in week one. The first is which of the two documented offer patterns a supplier fits: either it returns a single token that books N rooms, or each room's rate is independent and the offer list is the materialised matrix of valid combinations. There is no third pattern, so "which one is this" is a question with an answer rather than an investigation. The second is that hotel, flight and car search run asynchronously — a queue, one job per supplier, a Redis lock, workers writing into a shared cache hash plus a meta hash marking completion, all under an absolute 30-second deadline — while tour and transfer search run synchronously in a single process, behind the same public contract.
Two patterns and two execution models is four things to hold in your head. Ninety integrations is not. The documentation that says so was written for architecture reasons and turned out to be the onboarding material.
Week one is a booking, not a reading list
The first thing I ask a new engineer to do is run the entire booking flow once, by hand, against a test account: login, search, search-by-id, prebook, book, cancel. Not read about it. Run it, and watch what each step actually does.
This is safe because of a rule that exists for a different reason: a test booking always picks the cheapest offer with free cancellation, so a successful test can be unwound at no cost. The safety rule doubles as permission to let someone press the button on their second day.
An hour of that teaches things a diagram cannot. You watch a search return a progress fraction before it returns all its results, and the asynchronous model stops being a paragraph. You watch prebook succeed on a different process than the one that ran the search, and the composite offer ID — source, contract, hotel, uuid, decoded at prebook, no server-side session — stops being a design decision and becomes the thing that just happened to you. You watch a supplier answer HTTP 200 with an error inside the body, and you stop trusting status codes, which is a lesson every integration engineer learns eventually and may as well learn on day two.
Then one module, top to bottom
After the flow: read exactly one supplier module, end to end, including the ugly parts. Not a survey of five. One.
The point is depth on a representative instance. Ninety modules answer the same questions in ninety dialects, and you cannot hear a dialect until you know what the sentence is supposed to say. Every provider call is logged with its request and its response, and any failed call can be re-fired as the exact curl the platform sent — so the module can be read with its real traffic beside it, which is a completely different exercise from reading it cold.
Then a small change on a second supplier
The third step is a small task on a different supplier — small enough to finish, real enough to merge. This is where the contract earns its keep as a teaching device: the new engineer arrives with a mental model built on module one, hits the places module two disagrees, and learns that the disagreements live inside the module rather than leaking into shared code. That is the moment the shape-plus-exceptions idea stops being something I said in a meeting.
What makes any of this repeatable
Three things, none of them a tutorial.
Runbooks that execute. Roughly seventy procedures across three repositories exist as commands rather than wiki pages, so a newcomer who does not yet know how to reconstruct a failed booking can still reconstruct one. Written instructions rot silently; a command that runs is either correct or visibly broken.
A handbook that states requirements, not narrative. What a new integration must satisfy — which pattern it declares, what it logs, how it reports errors — written as things to satisfy. A newcomer can check their own work against it without asking me whether it is finished.
Blast-radius labels in the index. In one pack, 17 commands are read-only, 6 write to production and 1 deploys, marked 🟢/🟠/🔴 where the reader chooses, not inside the body where they find out afterwards. A new engineer is going to be guessing for weeks; the labels make the guesses safe ones. The same principle applies to the database: the standard client cannot reach the gateway database, so everyone uses a query script where a SELECT runs immediately and a write requires explicit confirmation after printing which host it is about to write to.
What I have not measured
I have no onboarding-time figure. Nobody timed anyone to first merge, before or after any of this existed, so I cannot tell you it got faster — only that the sequence is now the same for each person and does not depend on which of us was free that week. If someone hands me a "days to productivity" number for a system like this, my first question is what they defined as productive.