Hand the product over one domain at a time. Each domain comes with its tables, API and tests in one place, so signup is found under onboarding and nowhere else. The new engineer takes over one domain in week one, admin for example, while we keep payments.
Why does a handover from an agency go wrong?
When a product is built in the order the work arrives, signup ends up spread out. A route in one folder, a model in another, a script nobody remembers, tests grouped by whenever they were written.
Then you hire your first engineer. On Monday they ask where signup lives, and the answer is a list of places. Their first week goes to reading, and you can't tell from outside whether it's going well.
A handover document helps a little. It goes out of date the week after it is written.
The structure of the code has to carry the handover, because the document won't.
What does handover by domain mean?
A domain is one part of the product: onboarding, payments, admin, the AI layer if you have one.
Each domain has its own tables, its own API and its own tests. Nothing else writes to its tables directly. Other parts of the product ask through the API.
Signup is onboarding. So the user table, the signup endpoints, the email verification and the tests for all of it live in one place. If the new hire asks where signup lives, the answer is one folder.
This is how we run teams at Deciphering Logic. One team per domain, each owning its own data model, API and tests. We have shipped 30+ products for US and EU founders this way.
What should each domain hand over?
Four things, written down and checked in with the code:
- The data model. Tables, columns, and which of them other domains may read, through the API.
- The API. Every endpoint, what it takes and what it returns.
- The tests. Runnable with one command, with a plain description of what each group covers.
- The owner. A named engineer who answers questions about that domain.
The tests matter most. They show what the domain is supposed to do, in a form that fails loudly when someone changes it. A new engineer who can run them on day one knows the baseline before touching anything.
Run them in front of yourself too. You don't need to read code to watch a list of checks pass, and you can ask what a given group covers.
Why start the new hire on admin?
Admin reads from most of the product and writes to little of it. It shows the new engineer the other domains through their APIs, which is a quick way to see how the pieces connect.
It also carries less risk. A mistake in an admin screen is annoying. A mistake in payments touches money and customer records.
So the hire takes over admin in week one. They own its tables, its API and its tests, and they can ship a change on their own.
We keep payments for now. The hire hasn't yet seen production data or the edge cases in billing, and we have. Nothing about that is permanent.
What does week one look like?
Day one, you and the hire sit with the domain owner. Run the admin tests together, then read the admin API from top to bottom.
Days two and three, the hire reads the APIs of the neighbouring domains, onboarding first. They don't need the code behind them yet. They need the contract.
By the end of the week they ship one small change to admin through its own tests. A filter on a list, a new field on a user page. Something a real user can see.
Meanwhile payments carries on with our team, and the release doesn't wait on the hire getting up to speed.
How do you know the handover worked?
Ask the hire to find where signup lives without asking anyone. If it takes a few minutes, the structure is doing its job.
Check that the admin change went out through admin's tests only. If shipping it meant editing payments or onboarding files, the boundary is in the wrong place, and week one is a good time to find that out.
Check that the hire has written something down. A new line in the owner notes, a corrected endpoint description. That is a sign they have started to own the domain.
When does payments move to the in-house engineer?
When the hire has shipped a few changes in admin and read the payments tests end to end. There isn't a fixed date.
The handover uses the same four items: data model, API, tests, owner. The payments tables are documented, the tests run, and someone on our side stays reachable while the hire takes the first release.
Then onboarding, then whichever domain is next. One at a time, each with the same checks.
A second engineer later takes a domain the same way.
Does this work if the agency has already left?
Partly. The code is what it is, but the domain lines can still be drawn after the fact. Mapping each table to a domain, listing the endpoints and grouping the tests is work an engineer or a fractional CPO can do before the hire starts.
It gives the new engineer one folder per domain to start from, even if the old code only loosely follows it.
FAQ
How long does a software handover from an agency to an in-house engineer take?
The first domain changes hands in week one. The full handover depends on how many domains the product has. Each one moves when the hire has shipped in the previous one.
What should an agency hand over besides the code?
For each domain: the data model, the API description, runnable tests and a named owner. Repository and hosting access should go over on day one.
Can a non-technical founder check the handover?
Yes. Ask to see the tests run and ask what each group covers. Then ask the new engineer to say where signup lives.
If you are planning a handover and want to see how our domain teams are set up, the details are on the teams page.