Ahmad Almunajjed — Writing

What a team decides before its first microservice

Mon, 27 Jul 2026 00:00:00 GMT

Most writing about microservices argues about whether to adopt them. That argument has an answer for small teams, and I have made it elsewhere: a modular monolith gives you the same boundaries without the distributed system, and the triggers for splitting something out are specific enough to name.

This is about what happens after one of those triggers actually fires. A second team takes ownership, a component needs its own runtime, a compliance requirement forces isolation — and now the split is justified. The failure mode from that point is not choosing microservices. It is splitting along the wrong lines and discovering it eighteen months later, when moving a boundary means a data migration plus a versioned contract plus a coordinated rollout across two teams.

Four decisions do most of that work. This is the material I train teams on when they ask how to make the split without regretting it, and it was the substance of a five-day course I delivered to a government engineering team, in Arabic, on designing and implementing microservices with .NET.

Where does the boundary actually fall?

The boundary that survives is the one drawn around a business capability that owns its own decisions — not around a noun, and not around a layer.

The noun trap is the common one. “Customer” looks like an obvious service until you notice that sales, billing, and support each mean something different by it, need different fields, and change on different schedules. A “customer service” that all three call becomes a bottleneck that every team queues behind, which is the exact problem splitting was supposed to solve.

The test that works is about change rather than structure: if a single business change routinely requires coordinated releases from two services, the boundary is in the wrong place. One new field in a checkout flow should not require three teams to agree a deployment order.

A useful smell in the opposite direction is a service that everything depends on and that depends on nothing. That usually means the boundary was drawn around a data structure rather than a capability — it is a shared database with an HTTP interface in front of it.

Who owns which data, once it is across a network?

Inside one process, “each module owns its tables” is a discipline. Across a network, it is the whole design, because the moment a service needs data it does not own, you have to pick how it gets it — and every option costs something:

Approach	Consistency	Failure behaviour	Cost
Synchronous call to the owner	Always current	Caller fails when owner is down	Coupled availability
Replicate via events	Eventually consistent	Caller keeps working, data is stale	Must handle staleness explicitly
Shared database	Always current	—	Not a split at all

The third row is the one teams reach for under deadline pressure, and it silently undoes the entire exercise. Two services against one schema are one system with two deployment pipelines: the coupling is still there, it is just no longer visible in the code.

The second row is usually right, and the decision it forces is the one teams skip: how stale is acceptable, per field. A product name being a few seconds out of date is fine. A credit limit being a few seconds out of date is a business decision, not a technical one — and it is exactly the kind of question that should be answered with the business rather than assumed by an engineer at eleven at night.

What replaces the transaction?

This is the decision that surprises teams most, and it is the one that generates the most production incidents when it is not made deliberately.

Inside one process, a unit of work is one database transaction: it commits or it does not. Split across services, “place an order” becomes reserve stock, then charge the card, then create the shipment — three steps that can each fail independently, and one of which involves money.

There is no distributed transaction coming to save this. The realistic options are:

Compensating actions. Every step gets an explicit undo — release the reservation, refund the charge. Straightforward to describe, and the compensations are where the bugs live, because they are the paths that run least often.
Make forward progress the only direction. The order is accepted in a pending state and the system retries until each step succeeds, with a human queue for what never does. Usually the better fit for commerce, because a customer would rather wait than have their order silently vanish.

Both require idempotency at every step, and that is not optional. A retried “charge the card” that is not idempotent charges twice. In practice this means every operation carries a caller-supplied key and the receiver records what it has already done with that key — designed in from the first service, not added after the first duplicate charge.

The related decision is what the user sees meanwhile. A status that is derived from the steps that have actually completed is honest and survives partial failure. A status field that something remembers to update is a field that eventually disagrees with reality.

What has to exist before the first service ships?

A modular monolith fails loudly and locally: one stack trace, one log stream, in order. A distributed system fails quietly and somewhere else. The operational floor is therefore part of the architecture, not a follow-up ticket:

Correlation across services. One identifier, generated at the edge, present in every log line and every outbound call. Without it, “this request was slow” is not an answerable question — and adding it later means touching every service.
One place to read the logs. Logs sitting on five machines are five investigations.
Health and readiness that mean something, so a deployment fails on the branch rather than in production.
A defined answer to “who gets paged” for each service, agreed before the first incident rather than during it.

None of this is individually difficult. It is constant, and it comes out of the same budget as the product — which is the honest cost of the split, and the reason the split should be triggered rather than chosen.

The order these get decided

Boundaries first, because everything else follows from them. Then data ownership, because it is what makes a boundary real rather than decorative. Then the transaction question, because it decides what the system does when the network misbehaves — which it will. Then the operational floor, because without it you cannot see any of the above working.

Teams usually do this in reverse: infrastructure first, because it is tangible and there are tools to buy. That produces a well-monitored system with the boundaries in the wrong place, and no amount of observability fixes that.

This is the material I train teams on. If your team is at this decision, the course is built around your system rather than a generic example — see team training, or read the case for not splitting yet if the trigger has not actually fired.

Why a small team should start with a modular monolith

Sun, 26 Jul 2026 00:00:00 GMT

Microservices answer a question about people rather than about code. Once enough teams need to ship the same system without queueing behind each other, splitting the system along team lines starts to pay for itself. A company with one team of five engineers is a long way from that. Adopting the architecture anyway means paying the running costs of a distributed system to solve a coordination problem the company does not have yet.

The alternative is a single deployable application with real internal boundaries, which is a different thing from the tangled codebase people picture when they hear “monolith”.

What a modular monolith is

A modular monolith is one deployable application divided internally into modules that own their data and expose a narrow public interface. Modules call each other in process, through those interfaces, and never by reaching into each other’s tables. The boundaries are the same ones you would draw between services. What you leave out is the network between them.

The network is the expensive part

Once a call leaves the process it acquires failure modes that an in-process call does not have. It can be slow, it can be retried, it can succeed on the server and fail on the client, and it can arrive twice. Each of those needs handling code: timeouts, retries with backoff, idempotency keys, circuit breakers, and something that reconciles state when the retry lands anyway.

Data is the same story. A unit of work that used to be one database commit becomes a sequence of steps that can fail halfway through. You either accept that some states will be temporarily wrong and design around it, or you write a compensating action for every step. Both are real work, and both replace something a single transaction did for free.

Then there is everything around the code. Each service needs its own pipeline, its own configuration, its own alerting, its own place in whatever traces a request end to end, and its own answer to the question of who gets paged. Four engineers running six services own six of each. None of it is individually difficult. It is constant, and it comes out of the same budget as the product.

What one process buys you

Staying in one process costs a small team almost nothing, because nobody is waiting on somebody else’s release. In exchange:

A call between modules is a function call. It cannot time out, arrive twice, or half-succeed.
A unit of work is one database transaction. It commits or it does not.
A request produces one stack trace and one log stream, in order.
A release is one artifact through one pipeline.
A boundary you drew in the wrong place is a refactor, rather than a data migration plus a versioned contract plus a coordinated rollout.

That last point is the one people underestimate. Early on, the boundaries are guesses. Being able to move them cheaply is worth more than being able to deploy them separately.

Drawing the boundaries

The boundaries are the part worth the effort, and they are the same whether you deploy once or twenty times.

Cut along business capabilities, not technical layers. Ordering, inventory, billing, and notifications are modules. Controllers, services, and repositories are not. A layered cut produces a codebase where every feature touches every folder, which is the version of “monolith” everyone is afraid of.

Give each table exactly one owner. A module owns its data and no other module reads it directly. When ordering needs a stock level it asks the inventory module. This single rule does most of the work, because shared tables are the thing that makes a system impossible to separate later, and they are cheap to add and expensive to undo.

Keep the public surface small and explicit. A module exposes an interface and a set of types. Everything else is internal. Most languages can enforce that with their package or namespace system, and where the language cannot, a build check can.

Use in-process events for anything that is not the caller’s business. When one module needs to react to something another module did, publishing an event usually fits better than a direct call. Ordering does not need to know that notifications exist.

Keeping the boundaries honest

Boundaries decay under deadline pressure unless something enforces them. A build-time dependency rule that fails when a module imports another module’s internals is worth more than any diagram, because it fails on the branch instead of at the next architecture review.

Two failure patterns are worth watching for. The first is the shared common package, which starts life holding a date helper and ends up holding half the domain. If something is used by two modules, it probably belongs to one of them. The second is a module that everything depends on and that depends on nothing. That usually means the boundary was drawn around a data structure rather than a capability.

When to actually split something out

Extraction is a decision with a trigger. The triggers are specific:

A part of the system needs different hardware or a different runtime from the rest. Image processing, model inference, and long running jobs are the usual candidates.
A part needs to scale on its own axis, and scaling the whole application to serve it costs more than running it separately.
A second team takes ownership of something and the shared pipeline becomes the queue everyone waits in.
A compliance or data residency requirement forces isolation.

“We might need to scale one day” is not on that list. When one of the real triggers does fire, a module that already owns its data and exposes a narrow interface is most of the way to being a service: the interface becomes the API, the tables move with it, and the callers change one import.

That is the practical argument for building this way. The work that keeps a monolith modular is the same work that makes it splittable, so you get the option without paying for it up front.

This is the architecture I train teams on when they ask how to structure a system they will still be able to change in three years. The reason is unglamorous. For a team with more product to build than infrastructure to run, it keeps the most decisions open at the lowest running cost.

When one of those triggers does fire, the split has its own set of decisions — where the boundary falls, who owns which data across a network, what replaces the single transaction, and what has to exist operationally before anything ships. Those are the subject of what a team decides before its first microservice, which picks up where this post ends. Both are material I cover in team training.