Skip to content

feat(web): readable architecture graph with a focus mode - #262

Open
jplanckeel wants to merge 1 commit into
mainfrom
feat/web-architecture-graph
Open

jplanckeel wants to merge 1 commit into
mainfrom
feat/web-architecture-graph

Conversation

@jplanckeel

Copy link
Copy Markdown
Contributor

What

The Architecture page (/catalog/dependencies) could not be read nor used to answer "what does X need, what breaks if X fails". Checked on a catalog of 35 services and 52 links:

  • Layouts did not follow the dependencies. "Hierarchical" grouped services by their number of links (nodes stacked on top of each other, edges across the whole graph), "Force" placed them at random (Math.random, moving on every render), "Grid" and "Circular" ignored the links.
  • Animated dashed step edges, two color codes per node (SLA border + platform top border, ~20 platform colors), the graph pushed 700 px down under stats cards and a legend.
  • Only dependenciesIn was drawn: a link declared only in dependenciesOut was missing; dependencies outside the catalog were dropped; "Total Dependencies" counted each link twice.

New page

  • One layered layout with dagre, left to right: entry points on the left, databases and infrastructure on the right. A → B reads "A depends on B". No overlap (checked: 0 overlapping nodes out of 32), same result on every render.
  • Focus: click a service, or find it with the search box, to highlight what it depends on (blue) and what is impacted if it fails (teal), Direct or All levels; the rest is dimmed and the view frames that neighbourhood. A side panel shows SLA, platform, owner, both lists (clickable to move the focus) and Open service page (also on double click).
  • Links from both declarations are merged. A link declared by only one of the two services is dashed and counted in the header; a dependency outside the catalog (stripe-api, smtp-relay) is a dashed node.
  • Plain nodes of one size: name, platform icon, SLA dot with its label.
  • Header reduced to one line of counts; compact type / platform filters; services without dependencies hidden behind a checkbox; minimap in overview, hidden in focus (it covered framed nodes).
  • Zoom never goes below a readable level: a large graph opens on its entry points (top left) and is explored with the minimap.
  • Dark mode: nodes, edges, minimap and zoom controls follow the theme.

Removed

The four layouts, node sizes, the three stats cards, the SLA filter (the SLA stays on each node), the legend card, the list view (duplicate of the catalog and of the service page), the "large dataset" warning and the duplicated icon / color / label helpers. The page goes from 1 274 to ~530 lines.

Also

  • lib/dependencyGraph.ts: graph model (merge of both declarations, one-sided links, nodes outside the catalog) and reachability (direct / transitive, cycles), with unit tests.
  • @dagrejs/dagre 3.1.1, loaded with the page chunk only (CatalogDependencies 61 KB, 21 KB gzip). The 12 moderate npm audit advisories were already there without it.
  • docs/CATALOG.md and docs/USER_GUIDE.md describe the new page.

Checks

  • Playwright against serv + web/dist, light and dark: overview, search + Enter selects and frames payment-api (9 dependencies including stripe-api, 1 impacted), Direct / All levels, closing the panel, showing the services without dependencies, no JS error.
  • lint (0 issue), build:check, build:static, npm test (33, including 6 new): OK.

🤖 Generated with Claude Code

The four layouts did not follow the dependencies (nodes grouped by their
number of links overlapped, the force layout was random), edges were
animated dashed steps, and each node carried two color codes.

- One layered layout (dagre), left to right: A -> B reads A depends on B
- Click or search a service to highlight what it depends on and what is
  impacted if it fails, directly or at all levels, with a side panel
- Links from both declarations (dependenciesIn and dependenciesOut);
  links declared on one side only are dashed and counted, dependencies
  outside the catalog are dashed nodes
- Plain nodes: name, platform icon, SLA dot with its label
- Removed: the four layouts, node sizes, stats cards (one line instead,
  without double counting), SLA filter, legend card, list view
- Services without dependencies are hidden unless asked for

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant