Starting with a Legacy Monolith

A legacy monolith is not just old code in one deployment unit. It is also a store of business rules, workflow assumptions, reporting shortcuts, and organizational habits that have accumulated over time. That is why migration should not start with “Which service should we build first?” It should start with “Where is the system already showing boundary pressure?” Extraction based on intuition alone usually recreates old coupling in a new shape. Extraction based on evidence has a better chance of creating healthier boundaries.

The key lesson is that a legacy monolith already contains clues about future service seams. Change history, incident history, module dependencies, transaction pressure, and ownership confusion all tell you where the system wants stronger boundaries and where it still wants to stay together.

    flowchart TD
	    A["Legacy monolith"] --> B["Study change hotspots"]
	    A --> C["Study workflow call paths"]
	    A --> D["Study data ownership confusion"]
	    A --> E["Study operational pain"]
	    B --> F["Candidate boundaries"]
	    C --> F
	    D --> F
	    E --> F

What to notice:

• migration begins with diagnosis rather than extraction
• several evidence sources should point toward the same candidate
• boundaries found through real pressure are usually stronger than workshop-only boundaries

Why the First Extraction Often Goes Wrong

Teams often choose a first extraction candidate because it is:

• business-important
• politically visible
• familiar to one team
• easy to name in a slide deck

Those reasons are understandable. They are not sufficient. A capability can be important and still be a terrible first extraction if it sits at the center of transaction-heavy workflows, unclear ownership, or poorly understood legacy behavior.

This is why the first step should be diagnosis, not enthusiasm.

What to Study in the Monolith

Several evidence sources are especially useful:

• change history and release pain
• incident patterns
• dependency and call-flow analysis
• data ownership ambiguity
• reporting and integration exceptions
• places where teams already coordinate awkwardly

These signals help answer different questions. Change history shows where the system changes often. Dependency analysis shows what is entangled. Incident records show which parts of the system create operational pain. Taken together, they reveal where extraction might relieve real pressure instead of just redistributing code.

Change History Is a Boundary Signal

If the same set of files or modules changes together repeatedly, that is useful information. It may mean those parts still belong in one boundary. If one group of modules changes independently and causes its own release pain, that may indicate a better extraction candidate.

Even a simple query can help:

1select module_name,
2       count(*) as deployment_touches
3from deployment_change_log
4where deployed_at >= current_date - interval '180 days'
5group by module_name
6order by deployment_touches desc;

What this demonstrates:

• change frequency can be measured rather than guessed
• heavily touched modules deserve attention
• a hot module is not automatically a service candidate, but it is a boundary signal

The stronger analysis goes one step further and asks which modules tend to change together.

Workflow Pressure Matters More Than Code Layout

A monolith may already contain conceptual modules that look tidy in the repository. That does not prove they are ready for service extraction. The review must also ask:

• which workflows cross them?
• where do transactions rely on staying local?
• which user journeys depend on hidden shared state?
• which reporting or integration paths read across module boundaries?

This is where many migrations get surprised. A clean-looking module can still be deeply entangled in runtime behavior.

Ownership Clarity Is Part of Readiness

Legacy systems often accumulate fuzzy ownership. Before extracting anything, teams should ask:

• who understands the module well enough to own it?
• who gets paged when it fails today?
• who depends on it for roadmap delivery?
• who decides when its behavior changes?

If these questions have no stable answers, the architecture may need team clarification before or alongside extraction.

A Practical Monolith Review Record

1candidate: catalog
2change_pressure: high
3transactional_entanglement: low-medium
4runtime_dependency_depth: medium
5reporting_exceptions: medium
6team_ownership_clarity: high
7incident_isolation_today: medium-high
8first_extraction_bias: promising

What this demonstrates:

• a first candidate should be assessed across several dimensions
• strong candidates usually have real pressure and manageable entanglement
• readiness is about risk profile, not just importance

Avoid “Business-Critical Means First”

A common mistake is to extract the most central or sensitive workflow first because it feels important. In practice, the earliest extractions should usually help the organization learn:

• routing and traffic steering
• service ownership
• observability across boundaries
• contract evolution
• rollback and coexistence

Those lessons are often better learned on clearer, less transaction-heavy capabilities than on the deepest billing or fulfillment core on day one.

Design Review Question

A team wants to extract billing first because it is the most strategic domain in the monolith. Billing also has the highest transaction coupling, the most legacy integration dependencies, and the weakest current observability. Is strategic importance a strong enough reason?

Usually no. The stronger reasoning is that the first extraction should balance value with learnability and risk. If the domain is highly strategic but also highly entangled, it may be wiser to start with a clearer capability that lets the team learn routing, contracts, and ownership under lower risk before tackling the hardest core workflow.

Quiz Time