Engineering/Architecture

Modular monolith first: how I structure a SaaS from scratch without regretting it later

Microservices solve problems a new product doesn't have yet. The conventions I use to start with a well-split monolith that can grow and doesn't turn into a tangle.

Murilo Anzini 4 min read

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 useful question isn't "monolith or microservices?", but "where are the boundaries of my domain?". If the boundaries are good, extracting a service later is a task. If they're bad, not even microservices will save you.

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.

reports.controller.ts
@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.

#architecture#nestjs#saas#monolith

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.

About me

Free ebook

Criando infoprodutos de valor

The method I use to bring product, marketing and sales together when creating digital products: the way startups test hypotheses, understand needs and build what the market wants to buy.

  • Understand the customer and set the initial hypotheses
  • Build and test a lean MVP
  • Measure progress and validate with data
  • Know when and how to pivot
Download for freePDF · 23 pages · in Portuguese · no sign-up