Highly Coupled Codebases: How to Recognize and Refactor a Dependency Mesh (Updated 10JUN26)

Most architectural problems have a shape.

Stars have a center. Chains have a clear direction of flow. Circular dependencies form loops you can trace.

The Mesh has no clean shape.

That is the problem.

In this series, I use Dependency Mesh to describe a highly coupled codebase where dependencies have become so dense, bidirectional, and cross-cutting that the graph no longer shows clear boundaries. Instead of layers, clusters, and directional flow, you see a saturated tangle of edges running in every direction.

A dependency mesh is not just “messy code.” It is a structural condition where local reasoning breaks down. Understanding one module requires understanding many others. Refactoring one component touches unrelated areas. Circular dependencies overlap. Ownership boundaries blur. The graph stops helping you understand the system because the system has lost much of its internal separation.

A highly coupled codebase usually becomes a mesh gradually. One convenient import at a time. One shortcut around a boundary. One utility function placed in the wrong module. One “temporary” adapter that never gets removed.

The good news: even in a dense mesh, structure rarely disappears completely.

The goal is to find the surviving seams.

What a Dependency Mesh Looks Like

A dependency mesh is characterized by high edge density across the graph. Many modules depend on many other modules, and those dependencies do not follow a consistent direction.

In a well-structured system, the graph is relatively sparse. Most modules depend on a small number of others, and those dependencies usually follow patterns:

API → Services → Domain → Infrastructure

or:

Feature modules → Shared domain types → Infrastructure adapters

In a mesh, those patterns dissolve.

You might see:

• business logic importing from infrastructure
• infrastructure importing from domain models
• domain models importing utilities that import services
• API handlers importing directly from repositories
• service modules importing each other in both directions
• shared utilities depending on application-specific code
• circular dependencies crossing multiple layers
• no obvious boundary between features, infrastructure, and domain logic

No module has a clean stopping point. You follow one import, then another, then another, and eventually realize you are not tracing a path. You are inside a knot.

From a visualization standpoint, the difference is simple:

• Structured graphs have negative space. You can see clusters, layers, and boundaries.
• Mesh graphs collapse that space. Edges overlap so densely that structure disappears.

You do not see architecture anymore. You see saturation.

For the broader foundation behind these graphs, see What Is a Code Dependency Graph?.

Dependency Mesh Diagnostic Checklist

A codebase may be entering mesh territory if several of these are true:

• Edge count is several times larger than node count.
• Large strongly connected components cross architectural layers.
• Utility modules import domain, service, or API code.
• Domain logic imports framework-specific route or controller code.
• Small changes require broad manual regression testing.
• Developers cannot identify a safe place to start refactoring.
• New engineers struggle to find “where the logic lives.”
• Pull requests require reviewers from unrelated teams.
• The same concept appears in multiple layers because no single layer owns it.
• Deleting code feels dangerous because nobody knows what depends on it.
• Circular dependencies are not isolated; they overlap and share files.
• The dependency graph has no obvious clusters, layers, or low-coupling regions.

One or two of these signals does not mean the system is doomed. A mature codebase will have rough edges.

The concern is accumulation.

When many of these symptoms appear together, the codebase has likely moved beyond ordinary coupling into mesh behavior.

A Note on Graph Density

Mesh density is hard to quantify with a universal threshold because languages, frameworks, and repository styles differ.

A file-level graph in a small Python service will not have the same natural density as a TypeScript monorepo, a Java enterprise application, or a Rust workspace with multiple crates.

Still, edge density is a useful triage signal.

As a rough file-level heuristic:

edge density = dependency edges / nodes

A healthy graph often has a relatively low edge-to-node ratio. Many modules depend on a few things, and dependencies flow in predictable directions.

When edges begin reaching several times the node count — especially in the 5×, 8×, or higher range — structural problems often become visible. Not always, but often.

Treat density as a smoke alarm, not a diagnosis.

The more important questions are:

• Are dependencies directional?
• Are cycles isolated or widespread?
• Are high-density areas contained?
• Do clusters map to real domain boundaries?
• Are the densest modules stable abstractions or accidental dumping grounds?
• Does the graph still show seams?

Density tells you where to look. The graph tells you what is happening.

What It Feels Like to Work in a Mesh

The graph shows the structural problem. Daily development confirms it.

In a highly coupled codebase:

• A small change in one module breaks unrelated parts of the system.
• Pull requests require reviewers from multiple teams because ownership boundaries are unclear.
• Refactoring a single component becomes a multi-file, multi-system change.
• Developers hesitate to delete code because they do not know what depends on it.
• A single-function import pulls in three unrelated modules.
• Tests are hard to isolate because dependencies are tangled.
• New developers learn behavior through warnings and tribal knowledge instead of structure.

The most consistent symptom is loss of locality.

In a well-structured system, you can make changes within a bounded context. You can understand the local module, inspect its direct dependencies, run relevant tests, and make progress.

In a mesh, there is no reliable bounded context. Every change has an unclear blast radius.

That leads to predictable behavior:

• Teams avoid refactoring because it feels risky.
• New features are added with minimal structural consideration.
• Temporary shortcuts accumulate because cleanup is too expensive.
• Senior engineers become bottlenecks because they remember the hidden connections.
• The system becomes slower to change because every change requires coordination.

The problem is not only technical complexity. It is organizational drag created by technical structure.

How Dependency Meshes Form

Dependency meshes are not created in one architectural decision. They form through many small decisions that made sense at the time.

Deadline-Driven Shortcuts

The most common cause is sustained delivery pressure.

A developer needs a function. The function already exists somewhere. Importing it is faster than moving it, extracting it, or designing a cleaner boundary.

"I need this function. It is in that file. I will import it."

That decision is rational locally. Repeated across hundreds of features and hundreds of pull requests, it creates a graph with no clear direction.

Absence of Architectural Enforcement

Meshes form faster when there are no enforced boundaries between layers.

If any module can import any other module, developers under pressure will import whatever is convenient.

Over time, “whatever is convenient” becomes “whatever already has the behavior I need,” regardless of where that behavior belongs.

Without import rules, architecture is a suggestion.

Codebase Growth Outpacing Architecture

Many meshes began as reasonably structured small systems.

A codebase that works well with 20 modules does not automatically work well with 200. The original structure may stop fitting the system’s needs.

If no redesign occurs, new behavior is grafted onto the old structure in whatever way works. Eventually, the old structure disappears under accumulated dependencies.

Shared Utilities Becoming Load-Bearing

Utility modules often become hidden coupling centers.

At first, utils.py contains generic helpers. Then it gets a date formatter. Then a user display helper. Then a permission helper. Then a billing helper.

Eventually, utilities import business logic, and business logic imports utilities.

The module that was supposed to reduce duplication becomes a bridge between unrelated parts of the system.

For more on this pattern, see The Creeping Utility: How Helper Modules Become Load-Bearing Walls.

Mergers, Integrations, and Glue Code

Meshes often form when systems are connected after the fact.

Two codebases may each have had internal structure. But connecting them requires glue code that imports from both sides in ways neither architecture anticipated.

In the graph, this often appears as two clusters bridged by high-degree adapter modules.

Those bridge modules are important. They may be the start of the mesh, but they may also be the first place to recover structure.

Why Meshes Are Hard to Refactor

There Is No Safe Starting Point

Most refactoring begins with an isolated module: a place where you can improve structure without affecting much else.

In a mesh, isolation is rare. Modules are coupled to many others. Every change has indirect consequences.

The first question is not:

What should we refactor?

It is:

Where can we refactor without triggering half the system?

That is a harder question.

Circular Dependencies Overlap

Meshes contain overlapping cycles.

You may resolve one circular dependency and discover that the same module participates in three others. You are not removing a loop. You are untangling a knot.

This is where strongly connected components matter. A large SCC shows the real unit of coupling: the group of files that can all reach each other.

For a deeper explanation of SCCs, see What Are Circular Dependencies? Cycles, SCCs, and How to Fix Them.

Team Coordination Cost Increases

In a mesh, different teams modify overlapping parts of the graph.

Refactoring collides with feature work. Teams need to coordinate changes across modules they do not fully own. Reviews require more people. Release risk increases.

This makes structural improvement slower, not necessarily because the code is hard to edit, but because the organization has to coordinate around unclear boundaries.

Testing Surfaces Are Weak

Highly coupled systems are harder to test in isolation.

When modules cannot be imported independently, unit tests become harder to write. Teams rely more on integration tests or manual regression testing. That increases the risk of refactoring, which discourages refactoring, which lets the mesh continue.

The testing problem and the dependency problem reinforce each other.

Finding Surviving Structure

The first goal is not to fix the mesh.

The first goal is to find the structure that still exists.

Even dense graphs usually contain anchors: modules, clusters, or paths that remain more stable than the rest. Those are your starting points.

Look for Low-Density Clusters

Some groups of modules still have stronger internal connections than external ones.

These clusters may represent:

• preserved bounded contexts
• feature areas with clearer ownership
• parts of the system that changed less often
• modules built under stronger architectural discipline
• subsystems that are good candidates for extraction

Not every cluster is meaningful. Some are accidental.

To validate a cluster, ask:

• Does it represent a real domain concept?
• Do most changes inside it stay inside it?
• Does one team understand or own it?
• Are its external dependencies narrow enough to name?
• Could those dependencies be reduced without major surgery?

If the answer is mostly yes, the cluster may be a surviving seam.

For more on using graph structure to find boundaries, see The Hidden Seam: Using Your Dependency Graph to Find Microservice Boundaries.

Find the Acyclic Subgraph

Some modules do not participate in cycles.

These are valuable. They have clearer dependency direction, fewer hidden constraints, and better potential for isolation.

Treat acyclic modules as anchors:

• protect them from new back-edges
• improve their interfaces
• increase their test coverage
• use them as stable foundations for refactoring nearby modules

Do not let the mesh spread into the clean parts of the graph.

Identify Forced Entry Points

Every system has entry points that cannot simply be removed:

• API handlers
• CLI commands
• scheduled jobs
• message consumers
• webhooks
• plugin entry points

Trace what these entry points currently depend on. Then ask what they should depend on.

The gap between current dependencies and intended dependencies shows cleanup opportunity.

Example:

Current:
API handler → service → repository → model → API middleware → utility → service

Intended:
API handler → use case → domain → repository interface

The graph shows where direction collapsed.

Map Cross-Layer Edges

Cross-layer edges are high-value targets because they are explicit violations of intended architecture.

Examples:

domain → api
models → services
infrastructure → business workflow
utils → application service
repository → route handler

Not every cross-layer edge can be fixed immediately. Some are historical compromises. Some may be framework artifacts.

But cross-layer edges tell you where the architecture has failed most clearly.

Start there.

A Realistic Refactoring Strategy

Recovering from a mesh is not a weekend cleanup. It is sustained structural work.

For large, business-critical systems, meaningful recovery often takes months, not weeks. A 6–18 month range is realistic for severe cases when teams are actively prioritizing the work. Smaller systems or narrower mesh regions can improve much faster.

The strategy that works is incremental enforcement, not a rewrite.

Phase 1: Stop the Bleeding

Prevent new structural damage.

Before fixing old coupling, stop adding new coupling.

Introduce rules such as:

• no new cross-layer imports
• no new circular dependencies
• no new imports from API into domain
• no new imports from services into routes
• no new domain-specific logic in generic utilities

Enforce them in code review or CI where possible.

Tools like dependency-cruiser for JavaScript/TypeScript and import-linter for Python can help enforce dependency direction. Similar enforcement patterns exist in most major ecosystems.

This phase does not fix the mesh. It prevents the mesh from getting worse.

Phase 2: Protect the Acyclic Core

Find the parts of the graph that are still clean.

Then protect them.

For acyclic modules:

• improve tests
• clarify public interfaces
• document ownership
• prevent back-edges
• avoid convenience imports from mesh-heavy modules

These modules become stable ground.

Do not start recovery by attacking the worst knot in the system. Start by preserving the clean structure that still exists.

Phase 3: Shrink SCCs Incrementally

Work through circular dependency clusters from smallest to largest.

Small cycles often have obvious fixes:

• extract shared logic
• move type-only dependencies behind guards
• reverse dependency direction
• introduce an interface
• move orchestration up a layer

Large SCCs require more care. Do not try to untangle the whole SCC in one PR. Pick one edge, remove it, regenerate the graph, and repeat.

Progress is measurable:

largest SCC: 42 files → 31 files → 18 files → 7 files

Each reduction creates more local reasoning.

Phase 4: Enforce Layer Boundaries

Once cycles shrink, enforce direction more aggressively.

Move modules toward the intended architecture:

API → Use Cases → Domain → Infrastructure

or whatever layering fits your system.

This work is often mechanical:

• move functions
• update imports
• split modules
• replace direct calls with interfaces
• relocate framework-specific logic
• remove broad utility dependencies

It is not glamorous, but it steadily reduces graph density.

Phase 5: Extract Bounded Contexts

Once structure re-emerges, low-density clusters can become formal modules, packages, or services.

This is the payoff phase.

You are no longer trying to cut a service boundary through a knot. You are extracting around a seam that the graph already shows.

Good extraction candidates usually have:

• strong internal cohesion
• limited external dependencies
• clear ownership
• understandable entry points
• minimal participation in large SCCs
• a domain name that engineers and product people both recognize

This is where a mesh begins turning back into architecture.

Failure Modes During Mesh Recovery

Most mesh refactoring efforts fail in predictable ways.

Trying to Fix Everything at Once

Large rewrites usually stall.

The system is too coupled to change in one pass, and the effort collapses under its own coordination cost.

Pick one region. Pick one boundary. Pick one SCC. Make measurable progress.

Creating Worse Abstractions

Teams sometimes break direct imports by introducing a generic mediator, event bus, or service locator that everything flows through.

The graph may look cleaner, but the coupling has only moved.

If all business logic now depends on one opaque hub, the mesh has been hidden, not resolved.

A good abstraction reflects a real boundary. A bad abstraction launders coupling.

Enforcement Without Buy-In

Rules that forbid bad dependencies will be bypassed if teams do not understand why the rules exist.

Enforcement needs explanation:

• what boundary is being protected
• what dependencies are allowed
• how to solve common exceptions
• who can approve intentional violations
• when rules will become stricter

Otherwise, developers experience architecture rules as friction and work around them.

Temporary Glue Becoming Permanent

Adapters and bridge modules are often necessary during recovery.

But temporary glue has a habit of becoming permanent.

Track it explicitly:

temporary adapter
owner
reason it exists
planned removal condition
review date

If glue does not have an owner and a removal condition, assume it is permanent architecture.

Managing Refactoring Alongside Feature Work

The technical work is not the hardest part. Coordination is.

Mesh recovery competes with feature work for the same modules, same tests, same reviewers, and same release windows.

The approach that works:

• assign clear ownership of structural work
• define boundaries early
• require new code to follow new boundaries
• let old code improve incrementally
• track graph metrics over time
• protect refactoring time from feature pressure
• pair structural work with feature work when touching the same area

Do not rely on “we will clean this up later.”

That is how the mesh formed.

What to Measure During Recovery

Dependency graph metrics make recovery visible.

Useful measures include:

• total edge count
• edge-to-node ratio
• number of SCCs
• size of the largest SCC
• number of cross-layer edges
• high fan-in modules
• high fan-out modules
• number of modules in cycles
• acyclic module count
• test coverage around extracted seams

The goal is not to make every number go down. Some edge counts may increase temporarily when you extract interfaces or split modules.

The goal is direction:

• fewer cycles
• smaller SCCs
• clearer layers
• more acyclic regions
• lower coupling around first-change paths
• safer refactoring surfaces

A mesh recovery effort should be visible in the graph over time.

Conclusion

A dependency mesh is what happens when a system grows without sustained architectural attention.

It is one of the hardest patterns to recover from because it removes the natural starting points that most refactoring relies on. There are fewer isolated modules, fewer obvious seams, and fewer safe changes.

But structure rarely disappears completely.

Even in dense, highly coupled codebases, there are usually low-density clusters, acyclic modules, forced entry points, and cross-layer edges that point toward the next improvement.

Recovery starts from those anchors.

The dependency graph makes both the problem and the path forward visible. Before you can fix a mesh, you need to see it clearly. Once you can see it, the work becomes tractable — even if it takes sustained effort.

To diagnose this in your own repository, generate a dependency graph and look for edge density, SCC size, cross-layer edges, high fan-in/high fan-out modules, and surviving acyclic regions. PViz can help surface those signals for supported repositories for supported codebases.

Published in the Reading the Graph Series

The Star: When One Module Knows Too Much
High fan-in, high fan-out, and the module your entire codebase orbits around.

The Chain: Deep Dependency Paths and the Teams That Can't Ship Fast
How long linear dependency chains create invisible coupling between unrelated parts of your system.

The Hourglass: Your Most Dangerous Module Is Probably One You've Never Thought About
High fan-in above, high fan-out below — and a single module holding it all together.

The Island: Isolated Clusters and the Ownership Vacuum They Create
Why self-contained subsystems are more dangerous than they appear.

The Upward Arrow: When Infrastructure Knows About Business Logic
Abstraction inversion and how to fix it.

The Creeping Utility: How Helper Modules Become Load-Bearing Walls
The lifecycle of utils.py and how to intervene before it is too late.

The Hidden Seam: Using Your Dependency Graph to Find Microservice Boundaries
Graph structure reveals where your monolith already wants to split.