Handing a codebase from an agency to a first in-house engineer goes better when the code is split by domain and each domain carries its own schema, API and tests. This is the structure we use at Deciphering Logic and what the first week looks like.
The problem with layer-based layouts
A lot of codebases are organised by layer: controllers, models, services, tests. That works while the same people write everything. It makes handover slow, because one feature is spread across every layer.
Take signup. The route is in one folder, the user model in another, the email verification in a service, the tests in a directory named after whenever they were written. A new engineer asking where signup lives gets a list of paths.
Organise by domain instead
A domain is one part of the product: onboarding, payments, admin, an AI layer if there is one. Each domain owns its tables, its API and its tests.
A layout like this:
onboarding/
schema/
api/
tests/
payments/
schema/
api/
tests/
admin/
schema/
api/
tests/
Signup is onboarding. The user table, the signup endpoints, email verification and their tests sit under one directory.
The one rule that makes it work
No domain writes to another domain's tables. If admin needs a user's plan, it asks payments through the payments API.
That rule is what makes the folders mean something. Without it, the directories are cosmetic and a migration in one domain still breaks tests in another.
What each domain hands over
- Data model: tables, columns, and which ones other domains may read through the API.
- API: every endpoint, request and response shape.
- Tests: runnable with one command, with a plain note on what each group covers.
- Owner: a named engineer who answers questions about that domain.
The tests do most of the work. They describe what the domain should do and fail when someone changes that. A new engineer who runs them on day one has a baseline before editing anything.
Why admin goes first
Admin reads from most of the product and writes to little of it. Reading the neighbouring APIs from the admin side shows how the domains connect.
The risk is also lower. A bad admin change is a bug in an internal screen. A bad payments change touches money. So the hire takes admin in week one and we keep payments until they have read its tests and shipped a few changes elsewhere.
A week-one plan
Day one: run the admin tests with the domain owner, then read the admin API top to bottom.
Days two and three: read the APIs of the neighbouring domains, onboarding first. The contract is enough at this stage, the code behind it can wait.
By Friday: ship one small change to admin through admin's own tests. A list filter, a new field on a user page.
Payments keeps moving on its own backlog the whole time.
Checks that the handover worked
- The hire finds where signup lives without asking anyone.
- The admin change shipped without touching files in other domains. If it did touch them, the boundary is in the wrong place.
- The hire has edited the owner notes or corrected an endpoint description.
When the hire has shipped several admin changes and read the payments tests end to end, payments moves over with the same four items.
If the agency already left
The domain lines can still be drawn afterwards. Map each table to a domain, list the endpoints, group the tests by what they cover. The old code may only loosely follow the result, but the new engineer gets one directory per domain to start from.
More on how we set up domain teams: https://www.decipheringlogic.com/teams
Originally published at decipheringlogic.com
Top comments (0)