Monolith → microservices → API gateway: the three-diagram explainer

Three boxes. Ten boxes. One front door.

That's the entire monolith → microservices → API gateway journey, drawn small. Most posts pad it with two thousand words of definitions before showing you a single picture. Here are the three pictures. Then the words.

Diagram 1 — The single server#

The system most engineers ship first.

+-------------------+
|  Client (browser, |
|  mobile, partner) |
+---------+---------+
          |
          | 1 HTTP request
          v
+-------------------+
|   Monolith server |
|                   |
|   auth   users    |
|   posts  billing  |
|   email  search   |
+---------+---------+
          |
          | 1 in-process call -> 1 SQL query
          v
+-------------------+
|    One database   |
+-------------------+

In code: one repository, one deploy artifact, one database connection pool. A user clicks "Save profile". The browser makes one request. The server handles auth, validates the body, calls usersRepository.update(...), fires a single UPDATE, returns. Total network hops outside the box: one.

What this buys you:

• Function calls are free. Cross-feature calls (post creation calls the email sender, billing reads from users) are just imports.
• Transactions are easy. The whole update sits in one DB transaction; either everything happens or nothing does.
• Deployments are atomic. One image, one binary, one version of every line of code in the system.

What breaks first as you scale:

• The codebase grows past what one team can mentally hold. Onboarding takes weeks.
• One slow feature (a search query) blocks the whole process under load.
• One bad deploy takes the entire product down.
• The DB becomes the contention point. Locks across unrelated features creep into your p99.

This is roughly the 150-engineer wall. Below that, monoliths win on speed and clarity. The companies that split too early regret it; the ones that split too late regret it just as much.

Diagram 2 — Microservices, talking directly#

The reaction to those pain points.

+-------------------+
|       Client      |
+--+--------+----+--+
   |        |    |
   v        v    v
+------+ +------+ +------+
| Auth | | Users | | Posts |  ... + Email, Billing, Search
+--+---+ +--+---+ +--+----+
   |        |        |
   v        v        v
+----+    +----+    +----+
| DB |    | DB |    | DB |
+----+    +----+    +----+

Each feature is now its own process, with its own database, deployed on its own schedule. The client knows about all of them.

What changed structurally:

• Function calls became network calls. When posts needs the user's display name, it can no longer import { getUser } — it has to make an HTTP (or gRPC) call to users.
• Transactions are gone. Updating the user and creating a welcome post is now two writes to two databases. If the second fails, the first is already committed. You either accept the inconsistency or you build sagas.
• Errors compound. If auth is up 99.9% of the time and users is up 99.9%, your /profile endpoint that calls both is up 99.8%. With six services in the chain, you're at 99.4% — a ten-times-worse error budget.
• Observability becomes a project. A request that touches five services produces logs in five places. You need correlation IDs, distributed tracing, and a place to send all of it.

What this buys you:

• Each service can be owned, scaled, and deployed by a different team. The 150-engineer wall is now ten 15-engineer walls.
• A search query that's slow only slows down search. The rest of the product keeps responding.
• A bad deploy of email doesn't take down checkout.

But look at the picture: the client has to know every service exists. The browser is calling N hostnames. Auth tokens have to be re-presented to each. CORS has to be configured for each. When one service moves, every client breaks. This is the problem the API gateway exists to solve.

Diagram 3 — Behind an API gateway#

+-------------------+
|       Client      |
+---------+---------+
          |
          | 1 HTTPS request to one URL
          v
+-------------------+
|   API gateway     |
|                   |
|  auth check       |
|  rate limit       |
|  routing          |
|  retries          |
|  response shaping |
+--+----+-----+-----+
   |    |     |
   v    v     v
+------+ +------+ +------+
| Auth | | Users | | Posts |  ... + Email, Billing, Search
+--+---+ +--+---+ +--+----+
   |        |        |
   v        v        v
+----+    +----+    +----+
| DB |    | DB |    | DB |
+----+    +----+    +----+

The gateway sits in front of every microservice. From the client's view, the system looks like a monolith again — one URL, one auth, one error format. Behind the gateway, you can have ten or a hundred services.

What it does, concretely:

• Authentication. Verify the JWT once, reject unauthenticated requests at the edge before they cost you a service hop.
• Authorisation. Apply coarse-grained rules ("paid users only") so individual services don't reimplement the same check N times.
• Routing. POST /api/posts goes to posts-service; GET /api/users/:id goes to users-service. The client doesn't know either of those addresses.
• Rate limiting. Apply per-IP and per-user limits centrally.
• Retries and circuit breakers. When users is degraded, fail fast at the gateway instead of letting requests pile up.
• Response shaping. Take the raw responses from three services and assemble them into one payload the client actually wants. This is the "BFF" — backend-for-frontend — pattern.
• Observability. Every request enters and leaves through one place. Logging, tracing, metrics — all centralised.

The cost: the gateway is a new piece of infrastructure to operate, and it can become a bottleneck (or a single point of failure) if you don't run it carefully. Most teams pick a managed gateway (AWS API Gateway, GCP API Gateway, Azure API Management) or a battle-tested OSS one (Kong, Apache APISIX, Traefik, Envoy). Microsoft has a thorough write-up of the trade-offs if you want to go deeper.

The mental model that sticks: the API gateway is what makes your microservices look like a monolith from the outside. That's not an accident — that's the entire point.

Which one do you actually need?#

A short decision flow:

1. Are you a team of fewer than 20 engineers, on a single product? Stay on the monolith. You'll iterate faster and pay none of the operational tax.

2. Are you painfully blocked on deploys, scaling, or team boundaries? Extract one service first. A common starting point: pull out the slowest or most-rate-limited feature (search, image processing, email sending). Run it alongside the monolith. Don't build a microservices platform — build one service.

3. Do you already have three or more independent services? Add the API gateway now, not later. Every month you wait, more clients accumulate hard-coded URLs, duplicate auth code, and inconsistent retry behaviour. Migrating off direct-to-service routing later is twice the work.

4. Are you adding microservices because everyone else is? Don't. The architecture serves the team and the product, not the other way around.

What to take away#

A monolith is one box. Microservices are many boxes. The API gateway is the front door that hides how many boxes there are.

Each architectural step is a forced trade — you give up something (function calls, transactions, atomic deploys) for something else (independent scaling, smaller blast radii, team autonomy). The gateway is what makes the trade survivable for clients. Without it, "microservices" really means your client must now do the orchestration, which is almost always worse than the monolith you replaced.

Three boxes. Ten boxes. One front door. That's the whole picture.