Dependency map

The dependency map turns the flat asset list into a visual topology — who depends on what, who hosts what, who connects to what. It is the surface engineers reach for when they need to answer questions like "if I take this database down for an hour, what breaks?" and "which services share this certificate?".

Overview

AssetRelationship is the M2M join table that powers the map. Each row has a from_asset, a to_asset, a relationship_type (depends_on, hosts, connects_to, managed_by, part_of), an optional protocol / port, and free-form metadata. The map renders a node per asset and an edge per relationship.

Edges can be drawn manually, inferred from cloud-discovery output (an EC2 instance auto-links to its security groups and target groups), inherited from Kubernetes relationships (a Pod is part_of its Deployment), or generated by the cert-impact computation (cert_impact.py) which links every asset that consumes a given certificate.

Why it exists

A list cannot answer "what is downstream of this thing". A graph can, and engineers think in graphs. Putting topology, certificate coverage, and live status colour-coded into the same visual surface compresses what would otherwise be a three-tab investigation into a glance. Persistent layouts and shared annotations (WD.5) make the map a durable team artefact instead of an ephemeral whiteboard.

Key concepts

• Nodes — one per Asset. Colour reflects current status (operational, degraded, outage), shape reflects ci_type, size reflects relationship count (more connections = bigger node up to a cap), border thickness reflects criticality.
• Edges — one per AssetRelationship. Arrowhead direction reflects the relationship semantics (depends_on arrow points from the dependent to the dependency).
• cert-impact computation — when a CertificateSnapshot covers more than one asset (via SAN entries or wildcards), cert_impact.py synthesises virtual edges so a single failing cert lights up every consumer.
• DependencyMapLayout (WD.5) — saved positions per node, per workspace. The interactive layout persists pan, zoom, and drag-positioned coordinates so two engineers opening the map see the same picture. Each layout has a name; you can create per-environment or per-team layouts.
• Annotations — comment bubbles attached to a node or an edge, useful for "owned by team payments" or "deprecating Q3". Markdown-rendered, with @mentions notifying the mentioned user.
• Collaborative cursors — Django Channels WebSocket pushes cursor position and node-drag deltas to every viewer of the same layout in real time, so two operators investigating an incident see each other moving around.
• Blast-radius preview — submitting a change request from the change form opens a preview of the dependency map filtered to the change's target assets and their N-hop downstream. The preview is rendered alongside the change body so the approver sees impact before voting.

Common workflows

1. Explore the topology

1. Open Inventory → Dependency map.
2. The default view shows every asset in the current workspace using force-directed layout.
3. Pan by dragging the background; zoom with the scroll wheel (anchored to the cursor) or the +/− buttons in the toolbar.
4. Drag any node to reposition it. Dragged positions pin the node; the simulation respects manual placement on subsequent loads.
5. The toolbar's Reset layout button (rotate icon) releases all pins, recentres, and re-heats the simulation when the layout gets tangled.
6. Use the search input + environment / CI-type filter pills above the canvas to focus the view. Off-focus nodes dim to 25 % opacity instead of disappearing, so the overall shape stays legible.
7. Click any node to open the side detail panel: name, CI type, environment, upstream / downstream edges grouped by relationship type, current incidents, linked SLOs, certificates served.
8. Hover any node for a live tooltip with name + type + environment + neighbour count.

1b. Read the link styling

Each relationship type renders with its own colour and dash pattern, plus an arrow head showing direction:

• depends_on — red solid
• hosts — cyan solid
• connects_to — green solid
• managed_by — purple dashed (soft / organisational link)
• part_of — grey dotted (soft / organisational link)

The dual legend below the canvas matches the environment colour palette + the relationship-type palette so you can read the map without referring back to docs.

1c. Create + delete relationships from the map

The map is a first-class editing surface, not just a viewer:

1. Click the Link (chain) icon in the toolbar to enter Connect mode. The banner at the top of the canvas says "Click the source node".
2. Click the first node — it picks up a green ring + dashed halo, and a green dashed rubber-band line follows your cursor.
3. Click the target node. A picker dialog opens with the source → target preview and a relationship-type dropdown.
4. Submit. The new AssetRelationship row is created and the edge appears immediately with the right colour and arrow.
5. Press Esc at any point to cancel; clicking the background also cancels the source pick.

To delete a relationship, click any node to open its detail panel — each upstream / downstream entry shows a trash icon on hover. The confirmation dialog requires explicit acknowledgement before the row is removed.

2. Persist a layout and share it

1. Drag nodes into a meaningful arrangement (e.g. left-to-right by data flow).
2. Click Layout → Save as… and give it a name (e.g. payments-prod).
3. The layout writes a DependencyMapLayout row containing node positions and viewport state.
4. Share the URL — the layout name is encoded as ?layout=payments-prod, so colleagues open exactly your view.
5. Use Layout → Manage to rename, delete, or toggle between saved layouts.

3. Annotate a node

1. Right-click a node and pick Add annotation.
2. Type markdown. Use @username to notify a workspace member.
3. The annotation appears as a numbered pin on the node; clicking the pin opens the comment thread.
4. Annotations are part of the workspace audit log and survive layout changes.

4. Investigate a certificate's blast radius

1. From the Certificates page, open a snapshot detail.
2. Click Show on dependency map. The map opens in a popover focused on every asset linked to the snapshot via cert-impact.
3. Edges are coloured by the cert's status — green if healthy, red if expired.
4. Use Expand to N-hop to see who depends on those assets and how far the impact propagates.

5. Use the blast-radius preview when submitting a change

1. From the change request form, fill in the title, body, and target assets.
2. Click Preview impact next to the target list.
3. A side-by-side map opens showing the target assets in the centre and every transitive depends_on neighbour out to 3 hops (configurable).
4. Approvers see the same preview in the approval flow, so they can vote with full topology awareness.

6. Export the map for a document

1. File → Export offers PNG (current viewport), full PNG (entire layout), and PDF (auto-sized, vector).
2. PDF export includes the node and edge legend, layout name, workspace name, and export timestamp in the footer.
3. The export uses the current filter and layout, so combine filters first.

Permissions

The Channels WebSocket consumer enforces workspace scoping in connect(); a user can never observe cursor movement or annotations from a workspace they do not belong to.

Troubleshooting

Map is empty for a workspace with hundreds of assets. A filter is hiding the nodes. Click Filters → Clear all. If still empty, no AssetRelationship rows exist yet — add some manually, or run discovery (cloud or K8s) to bootstrap.

Layout saved on Monday looks scrambled on Wednesday. New nodes that did not exist when the layout was saved are placed using the default force algorithm. Drag them where you want and click Update layout.

Collab cursors do not appear. Channels requires a Daphne or ASGI worker; on self-hosted installs verify the WebSocket worker is running. The page also degrades gracefully — drag and annotation still work over REST.

Cert impact does not show the assets I expect. The cert-impact computation links to assets via the asset's hostname matching the cert's SAN list. If your assets do not have hostnames (e.g. database CIs), add an explicit connects_to relationship from the database to its TLS-fronting asset.

Export PDF is missing nodes that I can see on screen. Some browsers throttle off-screen canvases. Zoom out to fit the whole graph first, then re-export. For very large graphs, use the Full PNG export and let the server-side rasteriser do the work.

Related articles

• Asset CMDB — every node on the map is an asset row.
• Asset discovery — most relationships are populated by discovery, not by hand.
• Certificate monitoring — the source of cert-impact edges.