Microservices Architecture

The problem: one big app for many teams

We have an online shop. At the start, a team of 4 people built one app (a Monolith). Orders, inventory, payment and shipping are all in one project and one database.

Two years later, the company has grown. Now 5 teams work on the same app. The problems start:

1. Releases get slow. The payment team has a small change, but it must wait until the inventory team’s work is ready too. Because everything is released together.
2. One bug breaks everything. A memory leak in the reports part takes down the whole shop.
3. The load is not equal. Product search has a hundred times more load than placing orders. But to scale search, we must run more copies of the whole app.

The idea of Microservices is this: each part of the business is a separate app. Each team has its own service and its own database, and releases it whenever it wants.

Three ways to build a system

Between “one tangled app” and “dozens of separate services” there is a middle way: the Modular Monolith.

1. One app (Monolith). One app and one database. If the boundaries are not clear, all the code becomes dependent on all the other code.
2. Modular app (Modular Monolith). It is still one app and is released once. But each module has its own tables. Another module talks to it only through a public interface.
3. Separate services (Microservices). Each module is a separate app with a separate database. Calls go over the network.

The cost of Microservices

In one app, placing an order and decreasing the stock are in one transaction. Either both happen, or neither does. But in Microservices these two jobs are in two services and two databases. So:

1. There is no shared transaction. If the order is saved and the call to inventory fails, the data becomes inconsistent. To fix this, we need Outbox, Saga and compensating actions.
2. The network is not reliable. Every call may be slow, may fail or may arrive twice. So you need Retry, Timeout, Circuit Breaker and Idempotency.
3. Finding bugs is hard. One request goes through several services. Without Distributed Tracing and structured logs, you do not know where it broke.
4. Operations work multiplies. Instead of one release pipeline, you have ten. Each one needs its own monitoring, alerts and versioning.
5. Data is not the same right away. When services sync through messages, it takes a few seconds until all of them see the same thing (Eventual Consistency).

Where does a service boundary come from?

The biggest mistake is to build one service for each table: a customer service, a product service, a price service. The result: for every simple job, several services must call each other.

The right boundary comes from parts of the business. In DDD language, we call each part a Bounded Context. To find the boundary, ask these questions:

1. Which team owns this rule? The “maximum discount” rule belongs to the sales team. So it stays in the sales service.
2. Does this word mean the same thing everywhere? “Product” in sales means name, picture and price. In inventory it means quantity and shelf. So these are two separate models.
3. Which data changes together? Data that always changes together, in one transaction, must be in one service.

Each service, its own database

The main rule is: no service touches another service’s database directly. Not for reading, not for writing.

Why is a shared database bad? Step by step:

1. The order service and the inventory service use the same table.
2. The inventory team renames a column.
3. The order service breaks, because it still reads the old name.
4. From now on, the two teams must coordinate every change and release together.

This is called a Distributed Monolith: you have all the pain of the network, but no independence.

So if the order service needs inventory data, it has two ways:

• Call an API. When you need the answer right now. But be careful: for a list of 50 orders, do not call the service 50 times in a row. Collect all the ids and get them with one batch request.
• Keep a local copy. The inventory service publishes an event on every change. The order service keeps a small table with only the data it needs. The data is a few seconds behind, but reading it is fast and does not depend on inventory.

Synchronous calls or messages?

Services have two ways to talk:

Why is a long synchronous chain dangerous?

1. Imagine each service is healthy 99.9 percent of the time.
2. One request goes through 5 services in a row.
3. The probabilities multiply. So the total chance of success is about 99.5 percent.
4. This means the whole system fails about 5 times more than one service. The longer the chain, the worse it gets.

Code

The right start: Modular Monolith

Each module has a public contract. The rest of the code sees only this contract, not the internal tables and classes.

// Inventory module: the only public surface.
public interface IInventoryModule
{
    Task<bool> ReserveAsync(Guid orderId, IReadOnlyList<OrderLine> lines, CancellationToken ct);
}

// Everything else in the module is internal.
internal sealed class InventoryModule(InventoryDbContext db) : IInventoryModule
{
    public async Task<bool> ReserveAsync(
        Guid orderId, IReadOnlyList<OrderLine> lines, CancellationToken ct)
    {
        // Uses only the inventory tables (its own schema).
        // ...
        await db.SaveChangesAsync(ct);
        return true;
    }
}

If one day the inventory module really needs to be separated, only the implementation of this interface changes. The order code does not change.

After the split: calls with protection

When inventory becomes a separate service, the same contract is implemented with HTTP. Because the network is not reliable, we also add a Resilience layer:

builder.Services
    .AddHttpClient<IInventoryModule, InventoryHttpClient>(client =>
        client.BaseAddress = new Uri("https://inventory"))
    .AddStandardResilienceHandler(); // timeout, retry, circuit breaker

internal sealed class InventoryHttpClient(HttpClient http) : IInventoryModule
{
    public async Task<bool> ReserveAsync(
        Guid orderId, IReadOnlyList<OrderLine> lines, CancellationToken ct)
    {
        var response = await http.PostAsJsonAsync(
            $"reservations/{orderId}", lines, ct);
        return response.IsSuccessStatusCode;
    }
}

Non-urgent work: events

To send a text message, the order service does not wait for the notification service. It only publishes an event:

public sealed record OrderPlaced(Guid OrderId, Guid CustomerId, decimal Total);

This event must be sent together with saving the order, using the Outbox pattern. Otherwise the order may be saved but the event never goes out.

Key rules

1. Start with a Modular Monolith. Make the boundaries clear in the code. Delay the split until you have a real reason.
2. Split only for a real reason. Good reasons: several teams that do not want to wait for each other, a part with a very different load, or a part with a separate technical need.
3. Take the boundary from the business, not from the tables.
4. No shared database. Each service owns its own data.
5. Wherever you can, use messages instead of a synchronous chain. Keep synchronous chains short.
6. Have observability tools from day one. A trace id (Trace Id) in all services, structured logs and monitoring.

Common mistakes

When to use Microservices?