What problem does splitting a monolith actually solve?
A microservices migration fixes coupling between teams and their deployments. It does not fix bad code. If a module is tangled inside a monolith, cutting it out over a network keeps the tangle and adds latency, partial failures and versioned contracts to it. So before deciding when to split a monolith, work out which kind of pain you actually have.
Code-level pain lives inside the codebase. Modules reach into each other's internals, the test suite takes too long, and nobody can say who owns a given package. All of this can be fixed without a network boundary. Enforce module interfaces, split the test suite by module, and assign ownership in the repository.
Coordination pain lives between teams. One team's merge waits on another's review. Every change ships on a shared release train. One team's bad deploy or incident freezes releases for everyone else. A modular monolith reduces this but cannot remove it, because there is still one deployable artifact and one release decision. Independent deployment is the one thing a service boundary gives you that internal modularity cannot. That makes coordination pain the real argument for splitting.
| Pain type | Typical symptoms | Appropriate fix |
|---|---|---|
| Code-level | Circular dependencies, slow full test runs, unclear package ownership, changes that ripple across modules | Modular monolith: enforced module boundaries, per-module tests, ownership mapped in the repo |
| Coordination | Merge queues blocked by other teams, shared release trains, one team's incident blocking another's deploy, rollbacks that revert unrelated work | Extract services along team boundaries so each team can deploy and roll back on its own |
Who should consider a microservices migration? Reading your team topology
The strongest readiness signal is organizational. Conway's law says a system's structure tends to mirror the communication structure of the organization that builds it. In a monolith, that mirroring is already happening, but it's hidden: teams carve out informal territories inside one codebase and then pay the coordination cost at merge, test, and release time. A microservices migration lets you apply Conway's law deliberately, drawing service boundaries where team boundaries already exist.
This works when three conditions hold:
- Teams are stable and long-lived. A team that will own billing for years can absorb the cost of running a billing service: on-call, schema evolution, API versioning.
- Teams map to distinct business capabilities. "Payments" and "catalog" are capabilities. "Backend team" and "frontend team" are not, and splitting along technical layers produces services that must change together.
- Those teams keep colliding in one deployable. Collisions are the evidence that the shared artifact, not the code, is the bottleneck.
The opposite case is where migrations go wrong. If ownership is fuzzy, or the org chart is redrawn every few quarters, today's team boundaries are guesses. Inside a monolith, a wrong boundary costs a refactor. Across services, it becomes a network contract with consumers, a separate datastore, and a deployment pipeline, all of which resist change. You end up freezing a temporary reorg into infrastructure.
Small organizations rarely need to split at all. One or two teams that seldom block each other get little from independent deployment. They would take on distributed-systems overhead without removing any real coordination cost.
When is it time to split a monolith? The scorable readiness checklist
Before you score anything, pull evidence from your own systems: version control history, CI/CD pipeline records, and production metrics. Opinions in a planning meeting are not evidence. Answer each question yes or no, and try the cheaper fix before you count a "yes."
| Signal (yes/no) | Evidence to gather | Cheaper in-monolith fix first |
|---|---|---|
| Do multiple teams routinely edit the same modules and wait on each other's merges? | Merge conflicts per module; review time spent waiting on another team | Explicit module ownership, enforced internal boundaries |
| Are unrelated changes batched into one release? | Number of teams contributing to each release | Trunk-based development, feature flags |
| Do rollbacks revert other teams' work? | Rollbacks that took unrelated commits with them | Smaller, more frequent deploys; flags to disable one feature |
| Is lead time dominated by coordination, not build and test? | Pipeline data on how often another team's change blocks a release; queue time vs. execution time | Faster test suite, decoupling deploy from release |
| Do components have different scaling profiles, such as a CPU-bound batch job next to a latency-sensitive API? | Resource usage per endpoint and per job | Scale the whole monolith horizontally |
| Do components need different availability targets, or sit on opposite sides of a security or compliance boundary? | Agreed SLOs per capability; audit scope | Run a separate worker process from the same codebase |
The deployment questions tell you more than the code questions. Coordination cost grows with every team you add, and a team that cannot ship without permission from another team pays that cost on every release.
Rule of thumb: splitting is justified only when several coordination signals and boundary signals are true at the same time. A single pain point, such as one slow batch job, calls for a targeted fix rather than an architecture change.
How do you test whether a module boundary and its data are ready to extract?
Start with a concrete test. Name one module that exclusively owns its data: no other module writes to its tables, and the rest of the system interacts with it through a small set of operations you can list on one page. If you cannot draw that boundary inside the monolith, you cannot draw it across a network. A network only adds latency and partial failure to whatever coupling already exists.
The coupling is usually in the schema, not the code. Database-per-service ownership means that a module's tables are reachable only through that module's interface. Every place that breaks this rule needs a replacement:
- Cross-module joins become API calls, or local read models fed by events.
- Shared transactions become sagas. Each step commits locally, and a failed step triggers compensating actions such as refunding a charge or releasing a reservation.
- Reliable event publishing needs an outbox. The state change and the outgoing event are written in the same local transaction, then relayed to the broker, so neither can be lost without the other.
Each replacement trades immediate consistency for eventual consistency. The business has to accept that trade for every affected workflow.
If you split the code but keep a shared schema, you get a distributed monolith. Deployments stay coupled through migrations, and every call now crosses the network.
Enforce the boundary before extracting anything. Add an architecture test to the build that fails when one module imports another module's internal packages, or when a query references a table outside the module's owned list. Once that test stays green for a few release cycles, the boundary is real.
# test_module_boundaries.py: runs in CI and fails the build on boundary violations.
import ast, pathlib, re
SRC = pathlib.Path("src/app") # layout: src/app/<module>/..., private code in <module>/internal
# Each module's owned tables. Every other table is off limits to that module.
OWNED_TABLES = {
"orders": {"orders", "order_lines"},
"billing": {"invoices", "payments"},
"inventory": {"stock_items", "reservations"},
}
# Assumes the convention of uppercase SQL keywords, so prose like "from the" is not matched.
TABLE_REF = re.compile(r"\b(?:FROM|JOIN|INTO|UPDATE)\s+([a-z_][a-z0-9_]*)")
def violations():
for path in SRC.rglob("*.py"):
rel = path.relative_to(SRC).parts
if len(rel) < 2:
continue # skip files that are not inside a module package
module = rel[0]
for node in ast.walk(ast.parse(path.read_text(), filename=str(path))):
# Rule 1: never import another module's internal package.
names = []
if isinstance(node, ast.Import):
names = [a.name for a in node.names]
elif isinstance(node, ast.ImportFrom) and node.module:
names = [node.module]
for name in names:
p = name.split(".")
if len(p) >= 3 and p[0] == "app" and p[1] != module and p[2] == "internal":
yield f"{path}:{node.lineno} imports {name}"
# Rule 2: SQL string literals may reference only tables this module owns.
if isinstance(node, ast.Constant) and isinstance(node.value, str):
for table in TABLE_REF.findall(node.value):
if table not in OWNED_TABLES.get(module, set()):
yield f"{path}:{node.lineno} touches table {table}"
def test_module_boundaries():
found = list(violations())
assert not found, "Boundary violations:\n" + "\n".join(found)
A pytest architecture test that uses only the Python standard library and fails the build when one module imports another module's internal package or when its SQL strings reference a table outside the module's owned list.
What platform prerequisites must exist before the first service, and what do they cost?
The boundary is now ready. The platform usually is not, and every gap below gets paid for per service once you split.
| Prerequisite | Why it must exist before service #1 |
|---|---|
| Automated build and deploy per unit | Independent release is the main payoff. Manual deploys erase it. |
| Centralized logging, metrics, distributed tracing | A request now crosses processes, and a single stack trace no longer shows the whole path. |
| Service discovery and config management | Hard-coded hosts and per-box config files break as soon as instances move. |
| On-call ownership per service | Alerts that page nobody get ignored. |
| Self-service provisioning | A ticket queue for each new service pushes teams to bolt features onto existing services. |
Each service also carries its own pipeline, dashboards, alert rules, dependency upgrades and security patches. Local development gets harder. Engineers need contract tests, stubs for neighbouring services and ephemeral environments to run a realistic slice of the system.
You also take on failure modes the monolith never had:
- Partial failures: one dependency is down while the others are up.
- Timeouts: these must be tuned for every call between services.
- Retries that amplify load: retries can multiply traffic onto a service that is already struggling.
- Version skew: two deployed versions disagree on a contract.
Illustrative estimate (assumed numbers, not a benchmark)
Formula: overhead share = (N × h) ÷ (E × 40)
Assumed inputs:
- E = 6 engineers
- h = 2 hours per service per week for upkeep
- N = number of services
| Services (N) | Upkeep hours per week | Share of team capacity |
|---|---|---|
| 3 | 6 | 2.5% |
| 10 | 20 | about 8% |
| 20 | 40 | about 17% |
This counts only per-service upkeep, so the real cost runs higher. Integration testing and incident coordination grow with the number of connections between services, and that number rises faster than the service count.
How does an incremental strangler-style extraction work?
Start inside the monolith. Enforce module boundaries in the build so one module cannot import another's internals, and give each module sole ownership of its tables. If nothing outside the billing module writes to billing tables, extracting billing later is a deployment change. If many modules write to those tables, it becomes a long data-migration project.
Next, pick one well-bounded, high-value component. A good first choice is often one with divergent runtime needs, such as a CPU-heavy job or a spiky workload, because separating it pays off immediately. Put a routing layer in front and send that component's traffic to the new service while the old code path stays deployable.
┌──────────── Router ────────────┐
│ /billing/* ──► new service │
│ everything else ──► monolith │
└───────┬───────────────┬────────┘
▼ ▼
┌──────────┐ ┌───────────┐
│ Monolith │ │ Billing │
│ (old │ │ service │
│ path) │ │ │
└────┬─────┘ └─────┬─────┘
▼ sync / CDC ▼
[orders, users] ◄── [billing DB: owned
by service]
During the transition, keep data consistent with dual writes or change-data sync. Treat one side as the source of truth and reconcile the other side against it. Cut over when error rates and latency match the old path, reconciliation finds no drift, and rollback has been rehearsed. Then delete the old code and sync jobs, and reassess before choosing the next candidate.
This saves time compared with a big-bang rewrite. Each step ships value and can be reversed, and you never maintain two full systems in parallel. The risk is stopping partway through. A stalled migration leaves permanent dual writes and two sources of truth, which is worse than either the monolith or a finished split.
┌─────────────────── Router ─────────────────────┐
│ /billing/* ──► Billing service │
│ everything else ──► Monolith │
│ rollback = route /billing/* back to monolith │
└────────────┬──────────────────────────┬────────┘
│ │
▼ ▼
┌─────────────────────────┐ ┌──────────────────┐
│ Monolith │ │ Billing service │
│ orders, users modules │ │ extracted first: │
│ billing: old path, kept │ │ divergent runtime│
│ deployable for rollback │ │ needs │
└────────────┬────────────┘ └─────────┬────────┘
│ reads/writes │ sole writer
▼ ▼
┌─────────────────────────┐ ┌──────────────────┐
│ Monolith DB │ │ Billing DB │
│ orders, users tables │◄──│ source of truth │
│ billing copy: read-only │ │ for billing data │
│ replica, reconciled │ │ owned by service │
└─────────────────────────┘ └──────────────────┘
Billing DB ──► monolith billing copy via CDC / sync.
Cut over when reconciliation shows no drift, then
delete the old path and the sync job.
During a strangler extraction, the router sends billing traffic to the new service, which owns the billing database as the source of truth, while change-data sync keeps a reconciled copy available to the still-deployable monolith path until cutover.
When should you avoid splitting a monolith, and what are the alternatives?
Some reasons to split do not hold up on their own. "The codebase is old" describes age, not coupling. Wanting a new language is a taste or hiring question. "It's what large companies do" ignores why they did it: to coordinate many teams. A small team that rarely blocks itself has little coordination cost to remove. And expected performance gains usually reverse, because an in-process call becomes a network hop with serialization, timeouts and retries.
The common failure is the distributed monolith: services that must deploy together, share one database, or call each other in long synchronous chains. You pay the operational cost of services, keep the coupling of a monolith, and gain partial failures.
Wrong boundaries make this worse. Inside a monolith, moving a responsibility between modules is a single commit, and the compiler finds every caller. Across services, the same fix needs a versioned API change, a data migration between databases, and rollouts ordered so that old clients keep working.
| Option | Independence | Operational cost | Consistency |
|---|---|---|---|
| Modular monolith | Code ownership only | Low | Local transactions |
| Horizontal scaling | None | Low | Local transactions |
| Worker processes, one codebase | Separate scaling and runtime | Low–medium | Shared database |
| Targeted extraction | One component | Medium | Eventual, at one seam |
| Full microservices | Per service | High | Eventual, everywhere |
A modular monolith with enforced boundaries is often the correct end state, not just a waypoint. Extract a service only when a specific module needs independent deployment, scaling or ownership.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to when to split a monolith, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.