Monolith vs. microservices

  • Lesson 28 of 40
  • 14 min
  • Intermediate
  • 12 steps

One codebase or many services? What each option gives you, what it costs and how to move from one to the other without stalling the business.

Deploys
40/day
A bug takes down
one feature
Network hops per page
2–4
Ops overhead
high
shoppersAPIGatewayLoadbalancerAPIGatewayAPIGatewayAPIGatewayAPI GatewayMonolithevery featureMonolithMonolithevery featureMonolithone databaseUsersUsersCatalogCatalogOrdersOrdersPaymentsPaymentsusers DBcatalog DBorders DBpayments DBusers · catalog · orders · payments97%reports leak · out of memorydown · checkout tooone front dooreveryone shares the tablesA database per serviceno shared tablesno joins across servicesothers' data: API or eventseach team picks its engineAPI callslow · 2 stimeoutrelease train: all 4 togetherchained callshistory: 20 orders× 20 callslocal copy: name · photoProductChangedcontract: uses currencyCI: breaks the Orders contractcontract testedMonolith vs. microservicesMonolithMicroservicesTeamsone or a fewmanyDeploysall togetherindependentCallsin memoryover network, failDataone DB, joinsone per serviceOperationssimplemore toolingusers · catalog · orderseverything else/api/payments/*newAPI call
  • request
  • response
  • slow request
  • event
  • failed request

Step 1 of 12

Concept

One app, one deploy

Your online store is a monolith: a single codebase holding every feature (accounts, catalog, orders and payments), deployed as one unit. Two identical copies run behind a load balancer and both use the same database.

With a small team it is a great choice: one feature calls another in memory, one deploy ships everything and a single stack trace tells the whole story.

Step 2 of 12

Problem

Six teams, one codebase

The team grows to about fifty people split into six teams (example values). Everything ships in one weekly release, so one team's bug holds up everyone else's work.

A memory leak in the new reports module eats the RAM and takes down the whole process, checkout included. And if only search needs more resources, you still have to scale every copy of everything.

What changed

  • Six teams share one release
  • A reports bug takes down checkout
  • Scaling one feature means scaling everything

Step 3 of 12

Solution

Split by business capability

You break the app into microservices along business areas: Users, Catalog, Orders and Payments. Each one is a separate program, with one owning team and its own deploy pace.

An API gateway gives clients a single front door and sends every request to the service it belongs to. For now, all four still use the same database.

What changed

  • Monolith
  • Four services, one per team
  • API gateway

Step 4 of 12

Technique

Each service owns its data

As long as they share the database, the services are still tied: if one team changes a table, it can break three others without noticing. So each service gets its own database, and nobody else touches it.

Does Orders need to know whether a payment went through? It asks Payments through its API, or listens to the events Payments publishes.

What changed

  • Shared database
  • One database per service
  • Orders → Payments through its API

Step 5 of 12

Problem

There is a network in the middle now

To show one order page, the gateway calls Users, Catalog and Orders, and Orders calls Payments: 4 network calls where there used to be in-memory calls. Every hop adds latency and can fail on its own: here Payments takes 2 s (example value) and Orders gives up with a timeout.

Debugging now spans four repositories. You need timeouts, retries, distributed tracing and good dashboards (the Reliability module) just to get back to where the monolith started.

What changed

  • 4 network calls per page
  • Payments is slow and Orders times out
  • The page fails or degrades

Step 6 of 12

Problem

Case: the distributed monolith

A typical case (illustrative): a company splits its monolith into twelve services, but each one keeps reading the others' tables, and every new feature needs changes in five services released together.

They end up with the network costs of microservices and the coupling of a monolith. Releases get slower, not faster.

What changed

  • Services read other services' data
  • They must be released together
  • The worst of both worlds

Step 7 of 12

Problem

Case: the order history

The order history page shows each order with the product's name and photo. In the monolith that was a single SQL JOIN; now orders live in Orders, products in Catalog, and there are no joins across different services' databases.

So Orders calls Catalog once per order: 20 orders mean 20 calls plus the incoming one (the N+1 problem). The page gets slow and, if Catalog goes down, the history goes down with it.

What changed

  • The history needs Catalog data
  • 20 calls to Catalog per page

Step 8 of 12

Solution

Keep a local copy for reading

Orders keeps its own copy of the few catalog fields it shows: name and photo. Whenever they change, Catalog publishes a ProductChanged event and Orders updates its copy.

The history is one query to the Orders database again, and it keeps working even when Catalog is down. The price is not even looked up: the one that matters is the one that was paid, and it is already stored with the order.

What changed

  • ProductChanged events
  • Copy of name and photo in Orders
  • Calls to Catalog per page

Step 9 of 12

Technique

Case: an API change breaks a neighbour

The Payments team renames the field currency to currency_code. Their tests pass, they deploy… and every checkout in Orders starts failing. Deploying separately only works if one team cannot break another by accident.

With consumer-driven contract tests, Orders publishes exactly which fields it uses from the Payments API. The Payments pipeline checks those contracts before every release, and the change is stopped in CI instead of in production.

What changed

  • Orders publishes a contract for the Payments API
  • The breaking change is stopped in CI

Step 10 of 12

Trade-off

Which one suits you?

A common path: start with a modular monolith, a single deployable with strict internal boundaries between modules, and split a module out as a service only when a team truly needs independence.

Step 11 of 12

Technique

Migrating with the strangler fig pattern

Do not rewrite everything at once. Put the gateway in front of the monolith, build one new service (Payments) and send only /api/payments/* to it. Everything else still goes to the monolith.

Move one capability at a time until the monolith is small enough to retire. Every step can be shipped, and also rolled back. Meanwhile, a serious bug in the monolith still takes down almost everything: only payments stay safe.

What changed

  • Gateway in front of the monolith
  • New Payments service with its own database
  • /api/payments/* → new service

Step 12 of 12

Summary

Recap

A monolith is simple and fast until many teams have to share it.

Microservices are cut by business capability, and each one owns its data.

You pay with network calls, partial failures and more operational work.

Replace joins with local copies and protect APIs with contract tests.

Avoid the distributed monolith and migrate step by step with the strangler fig pattern.

You will learn

  • Where a monolith shines and where it hurts
  • Splitting by business capability
  • The cost of putting a network in the middle
  • Cross-service queries with local copies
  • Contract tests and the distributed monolith
  • Migrating safely with the strangler fig pattern