Skip to content

Dependency Mapping: Finding Hidden Connections in Your Codebase

Map dependencies in your codebase across imports, runtime calls, shared data and job order. Find hidden coupling and enforce useful architecture boundaries.

8 min read
A raised transparent model layer reveals hidden teal and brass connections beneath simple modules.
On this page

Last year I was asked to split a monolith into microservices. "It'll take a quarter," the VP of Engineering said. "The boundaries are pretty clear." They weren't. What looked like four independent modules turned out to be a web of 847 cross-module dependencies. The "simple split" took fourteen months.

The problem wasn't that the codebase was badly written. The problem was that nobody had mapped the actual dependencies. Everyone had a mental model of how things connected, and every mental model was wrong in different ways.

Dependency mapping discovers and documents connections between components in your codebase. Use it alongside the systematic codebase understanding guide when tracing an unfamiliar system.

The Five Types of Dependencies Most Teams Miss

Five types of dependency Static Imports and require statements Runtime Traces and dynamic calls Data Shared tables and cache keys Temporal Jobs and startup order Semantic Implicit business agreements
Figure 1. Inspect several kinds of evidence when mapping dependencies.

When developers think "dependencies," they think imports. But imports are just one of at least five types of coupling between components.

Type 1: Static Dependencies (Import/Require)

The obvious ones. Module A imports Module B. These are visible in the code and analyzable with tools.[1]

typescript
import { UserService } from "../users/UserService"; // Explicit dependency

Type 2: Runtime Dependencies

Dependencies that only manifest at runtime. Dependency injection, dynamic imports, reflection, and string-based lookups.

typescript
// This dependency is invisible to static analysis
const service = container.resolve(config.serviceName);

// So is this one
const handler = await import(`./handlers/${eventType}`);

Type 3: Data Dependencies

Two modules that share no code but depend on the same database table, the same cache key, or the same message queue topic. Change the schema, and both modules break.

typescript
// Module A writes:
await prisma.user.update({ where: { id }, data: { status: "active" } });

// Module B reads (in a completely separate file, no shared imports):
const activeUsers = await prisma.user.findMany({ where: { status: "active" } });

// If Module A changes "active" to "enabled", Module B breaks silently.

Type 4: Temporal Dependencies

Components that must execute in a specific order. The nightly batch job must complete before the reporting job runs. The cache must be warmed before the API starts serving traffic. These dependencies live in deployment scripts, cron schedules, and tribal knowledge.

Type 5: Semantic Dependencies

The most insidious kind. Two modules that share an implicit understanding about data format, business rules, or behavior. No code connection. No shared schema. Just an agreement that "status code 7 means the user has been soft-deleted" that exists only in two developers' heads.

Building Your Dependency Map

Step 1: Static Analysis

Start with what tools can find automatically.[2]

For JavaScript/TypeScript:

bash
# Install dependency-cruiser (more configurable than madge)
npm install -g dependency-cruiser

# Generate a dependency report
depcruise --output-type dot src/ | dot -T svg > deps.svg

# Or get a JSON report for further analysis
depcruise --output-type json src/ > deps.json

# Check for violations against your architecture rules
depcruise --validate .dependency-cruiser.js src/

Dependency-cruiser is my preferred tool because it lets you define rules about which dependencies are allowed:

javascript
// .dependency-cruiser.js
module.exports = {
  forbidden: [
    {
      name: "no-circular",
      severity: "error",
      from: {},
      to: { circular: true },
    },
    {
      name: "no-ui-to-data",
      comment: "UI layer should not import from data layer directly",
      severity: "error",
      from: { path: "^src/ui/" },
      to: { path: "^src/data/" },
    },
    {
      name: "no-cross-module-internals",
      comment: "Modules should only import from each other's index",
      severity: "warn",
      from: { path: "^src/orders/" },
      to: {
        path: "^src/payments/(?!index)",
        pathNot: "^src/payments/index\\.ts$",
      },
    },
  ],
};

For Go:

bash
# Built-in tooling
go mod graph
# Or for internal package dependencies
go list -json ./... | jq '.ImportPath, .Imports'

For Python:

bash
pip install pydeps
pydeps mypackage --no-show --max-bacon=3

Step 2: Runtime Dependency Discovery

Static analysis misses runtime dependencies. To find those, you need to observe the system running.

Approach A: Distributed tracing. Instrumented traces connect spans along an observed request path. Compare those paths with the static dependency report to investigate runtime connections. Sampling and instrumentation coverage affect which paths you can observe.[3]

Approach B: Log analysis. Add structured logging to module boundaries. Log every outbound call with the source and destination module. Run the system for a week. Aggregate the logs.

typescript
// Add boundary logging
logger.info("module_call", {
  from: "orders",
  to: "payments",
  method: "processPayment",
  correlationId: ctx.correlationId,
});

Approach C: Network analysis. For microservices, capture network traffic between services using a service mesh (Istio, Linkerd) or a network analysis tool. The network doesn't lie. If service A makes HTTP calls to service B, that's a dependency, regardless of what the documentation says.

Step 3: Data Dependency Discovery

This is where most teams have blind spots.

bash
# Find all modules that reference a specific database table
rg "prisma\.user\." --type ts -l

# Find all modules that read from a specific cache key
rg "cache\.get\(\"user:" --type ts -l

# Find all modules that publish or subscribe to specific events
rg "order\.created" --type ts -l

Build a matrix:

Data Resource Writers Readers
users table auth, admin orders, billing, reports, notifications
orders table orders billing, reports, fulfillment
user:session cache auth api-gateway, orders
order.created event orders payments, notifications, analytics, fulfillment

Every row with multiple writers is a coordination problem. Every row with many readers is a blast radius problem (changing the schema affects many modules).

Step 4: Temporal Dependency Discovery

bash
# Check cron schedules
crontab -l
# Or in Kubernetes
kubectl get cronjobs -o wide

# Check startup dependencies in docker-compose
grep "depends_on" docker-compose.yml -A 5

Build a timeline:

00:00 - Cache warmup job starts
00:15 - Cache warmup must complete before API health check passes
03:00 - Nightly data sync from external provider
04:00 - Report generation (depends on sync being complete)
06:00 - Email digest (depends on reports being generated)

Analyzing Your Dependency Map

Review the dependency map Examples follow the categories in the article. Circular dependencies Review the cycle Extract a shared concept Hub modules Inspect dependents Check stability and tests Shared data Identify readers/writers Define data contracts
Figure 2. Match the dependency problem to the boundary that needs investigation.

Once you have the map, inspect it for problems. The coupling and cohesion guide explains how to assess the boundaries, while codebase knowledge graphs connect these relationships with other evidence.

Problem 1: Circular Dependencies

Two modules depend on each other. The cycle can complicate independent testing, initialisation and changes. Its runtime effects depend on the language and module loader.

bash
# Find circular dependencies
depcruise --output-type err-long --validate .dependency-cruiser.js src/
# or
madge --extensions ts,tsx,js,jsx --ts-config tsconfig.json --circular src/

Fix: Extract the shared concept into a third module. If orders depends on payments and payments depends on orders, there's probably a shared concept (like MoneyCalculation or PricingRules) that both should depend on.

Problem 2: Hub Modules

A module with many incoming dependencies deserves review. Count its distinct dependent modules, then inspect the consumers and their contracts before estimating the impact of a change.[4]

bash
# Find the most depended-on modules (highest afferent coupling)
depcruise --output-type json src/ > deps.json
python3 - <<'PY'
from collections import defaultdict
import json

with open("deps.json", encoding="utf-8") as stream:
    report = json.load(stream)
dependents = defaultdict(set)
for module in report["modules"]:
    for dependency in module.get("dependencies", []):
        dependents[dependency["resolved"]].add(module["source"])
for target, sources in sorted(dependents.items(), key=lambda row: len(row[1]), reverse=True)[:10]:
    print(len(sources), target)
PY

Fix: If the hub module is a utilities grab-bag, split it into focused modules. If it's a core domain module, ensure it has excellent test coverage and stability guarantees.

Problem 3: Hidden Coupling Through Data

Two modules that look independent but share a database table. Changing one breaks the other without any compiler warning.

Fix: Define explicit data contracts. If the orders module needs user data, it should depend on a UserRepository interface, not directly on the users database table. This makes the dependency visible and testable.

I Was Wrong About Microservices Solving This

For years I believed that splitting a monolith into microservices would eliminate dependency problems. It doesn't. It transforms compile-time dependencies into runtime dependencies, which are harder to detect, harder to debug, and harder to fix.

In a monolith, an orders/payments cycle may fail a configured architecture rule or cause initialisation problems, depending on the language and loader. Across services, a circular call chain can amplify failures and complicate recovery.

The discipline of mapping and managing dependencies applies regardless of your architecture. Microservices don't remove the need for it. They increase it.

The Dependency Health Checklist

Run this assessment monthly:

  • Static dependency graph is generated and reviewed
  • No circular dependencies exist (or they're documented and scheduled for fix)
  • No module has more than 10 direct dependents (hub check)
  • Data dependencies (shared tables, caches, events) are documented
  • Temporal dependencies (job ordering, startup sequencing) are documented
  • Dependency-cruiser rules (or equivalent) run in CI
  • Architectural boundary violations are caught before merge
  • New dependencies require explicit justification in the PR description

The Dependency Decision Matrix

When you find a dependency problem, use this matrix to decide what to do:

Dependency Type Severity Action
Circular (static) High Break the cycle by extracting shared concept
Circular (runtime) Critical Break immediately, this causes cascading failures
Hub module (>10 dependents) Medium Split into focused modules over next 2 quarters
Data coupling (shared table, many readers) Medium Add explicit data contracts / repository interfaces
Data coupling (shared table, multiple writers) High Consolidate writes to one owner module
Temporal (undocumented) Medium Document in runbook, add monitoring for ordering violations
Semantic (implicit agreement) High Make explicit with shared types, schemas, or contracts

Getting Started

If you've never mapped your dependencies, start small. Pick one module. Run madge or dependency-cruiser on it. Look at the output. Are there dependencies you didn't expect? Circular dependencies you didn't know about? Connections to modules that seem unrelated?

Then pick the most surprising dependency and investigate it. Why does it exist? Is it necessary? Can it be removed or inverted?

That single investigation will teach you more about your codebase than a week of reading source code. Dependencies are the skeleton of your architecture. Once you see them clearly, everything else makes more sense.

Frequently asked questions

Does an import graph show every dependency?

An import graph shows the connections the parser can resolve from source code. Add runtime traces, shared-table access and job ordering to investigate relationships that a static report may omit.

How do I start dependency mapping in TypeScript?

Run a dependency analyser on one module and inspect its imports and cycles. Configure its TypeScript resolution and file extensions, then compare the graph with the module boundaries the team expects.

Should every circular dependency be removed immediately?

Assess the cycle against the language, loader and deployment model. Record whether it causes initialisation problems or forces coordinated changes, then decide whether to extract a shared concept or change the boundary.

How do I keep a dependency map useful?

Generate the static report in CI and check the boundary rules that matter to the system. Revisit runtime, data and temporal relationships as the application changes, since source analysis alone cannot establish them all.

Sources

  1. [1]GitHub - pahen/madge: Create graphs from your CommonJS, AMD or ES6 module dependencies · Madge maintainers
  2. [2]dependency-cruiser/doc/cli.md at main · sverweij/dependency-cruiser · dependency-cruiser maintainers
  3. [3]Traces · OpenTelemetry
  4. [4]dependency-cruiser/doc/output-format.md at main · sverweij/dependency-cruiser · dependency-cruiser maintainers

Checked against these sources on

Related Articles