Code dependencies are the structural relationships between modules, services, libraries, and data stores in a software system—including explicit dependencies (imports, function calls, API endpoints) and implicit dependencies (shared database tables, runtime configuration, event bus consumers) that don't appear in import statements. Understanding code dependencies is critical because they determine blast radius (what breaks when you change something), build complexity, and the true cost of refactoring or feature development.
Every software system is a graph of dependencies. Service A calls Service B. Module C imports Module D. Most teams can draw their service architecture on a whiteboard. Almost no team can describe their code dependency graph accurately.
This gap is where things break.
At Salesken, we had a production incident that started with a simple change to our STT (speech-to-text) service client. An engineer updated the timeout configuration. The STT client was imported by the coaching engine, which was imported by the event processor, which was imported by the analytics pipeline. The timeout change caused the coaching engine to fail faster, which sent a burst of error events to the event processor, which overwhelmed the analytics pipeline's queue. Four services affected. One config change. The engineer who made the change had no idea the coaching engine depended on the STT client's timeout behavior — it wasn't in any architecture diagram.
Dependencies are the hidden architecture of your system. Understanding them prevents incidents, makes estimates more accurate, and makes refactoring actually work.
What Are Code Dependencies?
A dependency exists when one piece of code requires another piece of code to work. If ClassA calls a method on ClassB, ClassA depends on ClassB.
Dependencies are directional. ClassA depending on ClassB is not the same as ClassB depending on ClassA. The direction matters because it determines the impact of change. If you change code that many things depend on, you risk breaking many things. If you change code that depends on other things, you only risk breaking itself.
At UshaOm, where I ran a 27-engineer team building an e-commerce platform, our most dangerous code wasn't the most complex — it was the most depended-on. The PriceCalculator module was imported by 34 other modules. A bug there would propagate everywhere. We didn't realize this until we mapped dependencies. The module that "felt" most critical (the checkout flow) was actually well-isolated. The module that was actually most critical (price calculation) was hidden in a utility directory.
Types of Code Dependencies
Direct dependencies are explicit. Code X calls Code Y. You can see it in the import statement. These are the easiest to manage because they're visible.
Transitive dependencies are indirect. Code X calls Code Y, which calls Code Z. X has a transitive dependency on Z even though it never mentions Z. Most systems have deep transitive chains. At Salesken, our coaching engine had a direct dependency on 8 modules. Transitively, it depended on 47. We only discovered this when we tried to extract it into a separate service.
Circular dependencies are dangerous. Code A depends on Code B, and B depends on A. This creates a cycle that makes code hard to test, hard to refactor, and prone to subtle bugs. At Salesken, our analytics pipeline had circular imports between the event processor and the aggregation engine. Every change to one risked breaking the other. We spent a sprint untangling them — worth every hour.
Implicit dependencies are the worst. Code A and Code B both read from the same database table or share global state. They depend on each other, but there's no import, no function call, nothing visible. At UshaOm, our product catalog and inventory modules had no direct code dependencies. But they both assumed the same database column format for SKUs. When the catalog team changed the SKU format, inventory broke. No static analysis tool would have caught it because the dependency was in the data, not the code.
Why Dependency Management Matters
Poorly managed dependencies cause cascading failures. You change one thing. Something else breaks. You fix that. A third thing breaks. I described this pattern in the incident management guide — our STT timeout cascading through four services was a textbook dependency cascade.
Dependencies hide true complexity. Your system might have five services, which sounds manageable. But if those five services have sixty dependencies between them, they're a tightly coupled monolith wearing a microservices costume. Adding features becomes slower because changes ripple through the network.
Dependencies also affect cycle time. At Salesken, we tracked which modules had the longest cycle times per PR. The correlation wasn't with code complexity — it was with dependency count. Modules with 20+ dependents had cycle times 2.5x longer than modules with fewer than 5, because every change required impact analysis across all those dependents.
Signs Your Dependencies Are a Problem
Deployments cause unexpected failures. You roll out changes to one service, and a completely different service starts failing. Hidden dependency.
Refactoring is painful. You try to extract a function, and everything breaks. More dependencies than you realized.
Estimates are consistently wrong. A task that should be two days takes a week. The extra time is discovering and handling dependencies you didn't anticipate.
Velocity is dropping. Features take longer and longer. Often, the codebase has become a dependency tangle where every change requires coordinating across multiple modules.
Circular dependencies exist. Module A imports Module B imports Module A. If you have these, fix them. They're never worth keeping.
How to Map Dependencies
You can't manage what you can't see.
For small systems (a few hundred files), a manual dependency diagram works. Draw boxes for main modules, arrows for dependencies. At UshaOm, we did this on a whiteboard quarterly. It took an afternoon and was always illuminating — engineers would discover connections they didn't know existed.
For larger systems, you need tooling. Static analysis tools scan your codebase and build the complete graph automatically. At Salesken, we used a combination of madge for our TypeScript services and custom scripts for our Python ML pipeline to generate dependency graphs.
Good dependency visualization shows:
- What each module imports and what imports it
- Circular dependencies (ideally highlighted in red)
- External dependencies and their versions
- Dependency depth — how many levels deep the chain goes
- Change impact — if I modify this module, what else might be affected?
The best approach is automated: when code changes, the dependency graph updates. Stale architecture diagrams are worse than no diagrams because they create false confidence.
Managing Dependencies in Microservices
Microservices should be independent. In practice, they're interdependent. The goal isn't zero dependencies — it's well-managed dependencies with clear contracts.
Prefer async communication. If Service A calls Service B synchronously, they're tightly coupled. If A writes to a queue and B reads from it, they're decoupled. B can be slow or down, and A still works. At Salesken, we moved our analytics pipeline from synchronous API calls to an event bus. When the analytics service went down for maintenance, the rest of the system kept running. Events queued up and processed when it came back.
Use API versioning. If Service A depends on Service B's API, both need coordinated upgrades when the API changes. Versioning lets you decouple the upgrade. We learned this the hard way — a breaking API change in our user service required simultaneous deployment of three dependent services. After that, we enforced semantic versioning with backward compatibility for at least two versions.
Use service contracts. Define what Service A expects from Service B. This way, B can change internals without breaking A's assumptions. Contract testing catches mismatches before production.
Monitor dependency health. Which services call which other services? How long do those calls take? Are there timeouts? At Salesken, we added distributed tracing after the STT cascade incident. Within a week, we discovered 3 other dependency chains we didn't know about.
Hidden Dependencies That Tools Miss
The hardest dependencies to manage are the ones that don't show up in code analysis.
Database schema dependencies. Two services read from the same table. Change the schema, both break. At UshaOm, we had 6 services reading from the products table. A migration that added a NOT NULL column broke 4 of them.
Shared configuration. Services that read the same config file or environment variables are implicitly coupled. At Salesken, we had a feature flag configuration that three services read from. Changing a flag for one service accidentally affected the other two.
Timing dependencies. Service A assumes Service B processes events within 5 seconds. No code imports. No API contracts. Just an assumption about timing. When B gets slow, A breaks in ways that are nearly impossible to diagnose from the code alone.
Data format dependencies. One service writes JSON with a specific field structure. Another service reads it. Neither imports the other's code. The dependency lives in the serialization format. At Salesken, we added a metadata field to our event payload. The analytics service expected the old format. No tests caught it because each service tested in isolation.
FAQ
What's the difference between dependencies and coupling?
Dependencies are the structural relationships between code. Coupling is the degree to which changes propagate. High dependency can mean high coupling, but well-designed dependencies (clean interfaces, dependency injection) can have low coupling. The goal isn't fewer dependencies — it's lower coupling. Dependency mapping helps visualize where high coupling exists so teams can prioritize refactoring efforts.
Should we eliminate all circular dependencies?
Yes. Circular dependencies are a code smell that makes testing hard and refactoring dangerous. If you have them, the modules should be merged (they're really one module) or restructured (extract the shared dependency into a third module).
How do we update dependencies safely?
One at a time. Update a dependency, run tests, deploy, monitor. Then move to the next. At Salesken, we batched 12 dependency updates into one PR once. Three of them conflicted. It took longer to debug than doing them individually would have. Monitoring change failure rate after each update provides an early warning signal if a dependency introduces regressions.
Is it okay to depend on many things?
If a module imports ten well-designed, minimal modules, that's fine. If it imports ten modules because it's doing ten unrelated things, it should probably be split. The smell isn't the count — it's the cohesion.
Related Reading
- Code Refactoring: The Complete Guide to Improving Your Codebase
- Dependency Mapping: Visualize and Control Your Codebase
- Design Patterns: When They Help, When They Hurt, and How to Choose
- Incident Management: From Alert to Resolution to Prevention
- Clean Code: Principles, Practices, and the Real Cost of Messy Code
- CI/CD Pipeline: The Definitive Guide to Continuous Integration & Delivery
- Code Dependency Analysis
- What Is Code Dependencies?