Every time I start a product from scratch, the temptation shows up: "let's do microservices from the start, so it scales". And every time the answer is the same: scale what? A new product doesn't have a scale problem. It has the problem of finding out whether anyone wants to use it. The right architecture for that phase is the one that lets you change your mind fast.
For me, that architecture is a modular monolith: a single deploy, a single database, but split by domain with clear boundaries. Simple to run today, easy to break apart tomorrow if needed.
Why not microservices right away
Microservices trade code complexity for operational complexity. You gain independent deploys and autonomous teams, and you pay with network calls between services, eventual consistency, distributed observability, contract versioning and infrastructure that needs people to look after it.
That price is worth it when you have many teams stepping on the same code or parts of the system with very different scaling needs. In a product with a small team and a few hundred users, it's just cost.
The conventions that hold the monolith together
A monolith only turns into a tangle when it has no rules. These are the ones that help me most, using NestJS as the example (the idea applies to any stack):
1. One module per domain
Each business domain lives in its own folder, with controller, service, entities and tests together. There's no services/ folder with everything mixed in.
src/modules/
auth/
billing/
projects/
reports/
mail/
2. Modules aren't global
If the reports module needs the projects module, it declares the import. It looks like bureaucracy, but it's what makes dependencies visible. When the graph starts to look odd (everyone importing everyone), you see it before it becomes a problem.
3. A single HTTP contract
Every response comes in the same envelope and every error in the same format. I use { data, meta } for success and Problem Details for errors, applied globally. The controller returns the raw data and doesn't worry about the format.
@Get(':id')
async findOne(@Param('id') id: string, @CurrentBusinessId() businessId: string) {
// Just the data: the { data, meta } envelope is applied by a global interceptor
return this.reports.findOne(businessId, id)
}
The front end is grateful: a single HTTP client, a single way of handling errors.
4. Expected errors have a type and a code
throw new Error('not found') becomes a 500 and hides the intent. An expected error is a class (NotFoundError, BusinessRuleError) with a stable code that the front end can translate and support can search for in the logs.
5. Contract tests
For each route, a test records the shape of the response in a reference file. Changed the contract by accident? The test fails. Changed it on purpose? You re-record it and review the JSON diff in the PR. It's cheap and catches exactly the kind of regression that silently breaks the front end.
Multi-tenant from day one
If the product is B2B, one rule is worth its weight in gold: the tenant never comes from the client. The company id comes from the authenticated user's membership, in a decorator, and every access to domain data filters by it. It sounds obvious, but it's the kind of thing that, if it isn't in the foundation, turns into a painful audit later.
Documentation that lives with the code
Architecture that only exists in someone's head isn't architecture, it's folklore. I keep a docs/ folder in the repository with:
- An architecture overview and the decisions behind it;
- Checklists (what every new route needs to have);
- Known technical debt, so nobody assumes something works when it doesn't;
- Decisions (ADRs), short, with the context of when they were made.
Every doc has a "verified on" date. Changed the behavior? Update the doc in the same commit. That's what lets someone else (or an AI agent) work on the code without breaking the rules.
When to leave the monolith
The signs that it's time to extract a service are concrete:
- A module needs to scale very differently from the rest (heavy processing, queues, spikes);
- Different teams keep blocking each other on the same deploy;
- A domain has isolation requirements (security, compliance) that justify the separation.
If the boundaries were respected, extracting that module means moving a folder and swapping function calls for network calls. If they weren't, you find out the "module" talks to half the system.
Summary
Start simple, but with discipline. A modular monolith with modules per domain, explicit dependencies, a single contract, typed errors, contract tests and living documentation gives you the speed a new product needs and the structure to grow when (and if) the product asks for it.
Murilo Anzini
Hands-on writing on engineering, product, data and marketing for people who want to understand, and build, the whole journey of a product.
The whole journey: why engineering, product, data and marketing need to fit in the same conversation
Good products are born when four questions are asked together: what to build, how to build it, how to know it worked and how to reach the people who need it.
A North Star without vanity: how to choose the metric that really guides the product
Registered users, pageviews and downloads make pretty charts and bad decisions. A guide to choosing the metric that matters and building the tree that connects the team's work to it.