Dependencies

Dependencies are relationships that show when one landmark relies on another. They answer the question: “If this service goes down, what else is affected?”

What Are Dependencies?

A dependency is a directional relationship between two landmarks. When landmark A depends on landmark B, it means:

• A requires B to function properly
• If B fails or changes, A is affected
• A cannot operate normally without B

Dependencies are most commonly used between services, but they can connect any type of landmark. For example:

• The Billing API depends on the PostgreSQL database
• The Client Portal depends on the Auth Service
• The Deployment Pipeline depends on the CI/CD Platform

Dependencies are different from associations. Dependencies imply a hard requirement; associations imply a loose connection. See Associations for details on when to use each.

Why Dependencies Matter

Dependencies provide critical context for decision-making:

Impact analysis: When you need to update or decommission a service, dependencies show you what else will be affected. Before changing PostgreSQL, you can see which services depend on it and plan accordingly.

Incident response: When a service fails, dependencies help you understand the blast radius. If the Auth Service goes down, you can immediately see which services are impacted and prioritize recovery.

Architecture documentation: Dependencies create a living map of your system architecture. Instead of static diagrams that become outdated, dependencies are maintained alongside the services they describe.

Onboarding: New team members can quickly understand how services relate to each other by exploring the dependency graph. This reduces the time needed to learn the system.

Capacity planning: When a dependency approaches its limits, you can see which services will be affected and plan for scaling or migration.

How to Create a Dependency

Dependencies are created during entity creation or editing. In the entity wizard, Step 4 (Organization) includes a Relationships section.

To create a dependency:

1. Open the landmark you want to define dependencies for
2. Click Edit to open the editing wizard
3. Navigate to Step 4 (Organization)
4. In the Relationships section, find the Depends On field
5. Search for and select the landmark(s) this entity depends on
6. Click Save to apply the changes

You can add multiple dependencies to a single landmark. For example, the Billing API might depend on PostgreSQL, Redis, and the Auth Service.

To remove a dependency:

1. Open the landmark’s detail drawer
2. Click the Relationships tab
3. Find the dependency you want to remove
4. Click the trash icon next to the relationship
5. Confirm the deletion

Viewing Dependencies

Dependencies are visible in multiple places throughout Legend:

Entity card: The entity card shows relationship indicators, including “depends on” and “depended on by” counts. These badges give you a quick overview of the dependency structure.

Detail drawer: The Relationships tab in the detail drawer lists all dependencies. You can see what the entity depends on and what depends on it. Click any related entity to navigate to its detail view.

Topology explorer: The topology graph visualizes dependencies as directed edges between nodes. This provides a clear picture of the dependency chain and helps you understand the system architecture at a glance.

Search results: When you search for a landmark, the search results include related entities. Dependencies are shown as part of the relationship graph, helping you discover connected services.

Dependency Direction

Dependencies are directional. When landmark A depends on landmark B:

• A is the dependent (it requires B)
• B is the dependency (it is required by A)

The direction matters for impact analysis. If B fails, A is affected. If A fails, B is not affected (unless B also depends on A, which would create a circular dependency).

Circular dependencies: Legend allows circular dependencies (A depends on B, B depends on A), but they are generally a sign of poor architecture. If you encounter circular dependencies, consider refactoring the services to break the cycle.

Best Practices for Dependencies

Be specific: Define dependencies at the service level, not at the component level. For example, “Billing API depends on PostgreSQL” is clearer than “Billing API depends on database.”

Document the reason: If the dependency is not obvious, add a note in the documentation explaining why the dependency exists. This helps future maintainers understand the relationship.

Review regularly: Dependencies change as systems evolve. Periodically review dependencies to ensure they accurately reflect the current architecture. Remove dependencies that no longer exist and add new ones as services are created.

Use dependencies for impact analysis: Before making changes to a service, check what depends on it. Communicate with the owners of dependent services to coordinate changes and minimize disruption.

Keep dependencies current: When a service is decommissioned, update all entities that depend on it. Remove the dependency or redirect it to a replacement service.

Dependencies in the Topology Explorer

The topology explorer provides the most comprehensive view of dependencies. When you explore a landmark, the graph shows:

• The landmark at the center
• All landmarks it depends on (outgoing edges)
• All landmarks that depend on it (incoming edges)
• The depth of the dependency chain (how many levels deep to traverse)

You can adjust the depth selector to explore deeper dependency chains. For example, setting depth to 3 shows not only direct dependencies but also dependencies of dependencies.

Navigating the topology:

• Click any node to navigate to that landmark
• Use breadcrumbs to trace your exploration path
• Zoom and pan to explore large dependency graphs
• Use the minimap to orient yourself in complex graphs

Dependencies vs Ownership

Dependencies and ownership are different types of relationships:

Ownership:

• Shows who is responsible for a landmark
• A landmark has one owner (team or person)
• Ownership answers “who do I contact about this?”

Dependencies:

• Shows what a landmark requires to function
• A landmark can have multiple dependencies
• Dependencies answer “what does this need to work?”

A landmark can have both an owner and dependencies. For example, the Billing API is owned by the Payments Team and depends on PostgreSQL and the Auth Service.

Related

Associations

Ownership

Topology Explorer