Skip to content

AI-native knowledge base & Evernote/Obsidian alternative with instant sync & native MCP. Free on Cloudflare or self-hosted via Docker.

fix(diagram): clarify dense architecture connections

tianma-iff8233d9f20c9
diff --git a/apps/web/src/components/DiagramEditorPane.tsx b/apps/web/src/components/DiagramEditorPane.tsx
index daad8885..c88b3e30 100644
--- a/apps/web/src/components/DiagramEditorPane.tsx
+++ b/apps/web/src/components/DiagramEditorPane.tsx
@@ -1,4 +1,5 @@
import { diagramEditorSnapshot } from "@/lib/diagram-editor-snapshot";
+import { focusArchitectureRelations } from "@/lib/architecture-relations";
import { MemoTitleInput } from "@/components/MemoTitleInput";
import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState, type DragEvent as ReactDragEvent, type PointerEvent as ReactPointerEvent, type ReactNode } from "react";
import { Dom, Export, Graph, History, Keyboard, Scroller, Selection, type Edge, type Node } from "@antv/x6";
@@ -116,7 +117,9 @@ import {
ARCHITECTURE_NODE_LINE_HEIGHT,
ARCHITECTURE_SHAPE_RESOURCE,
architectureEdgePorts,
+ architectureEdgeTerminals,
architectureEdgeRouter,
+ architectureTerminalAnchor,
architectureEdgeVisual,
architectureIconOffset,
architectureNodeVisual,
@@ -1376,6 +1379,14 @@ const applyOrthogonalEdgePorts = (graph: Graph, kind: DiagramDocument["kind"]) =
const boundaryIds = kind === "architecture"
? graph.getNodes().filter((node) => node.getData<NodeData>()?.shape === "boundary").map((node) => node.id)
: [];
+ const architectureTerminals = kind === "architecture"
+ ? architectureEdgeTerminals(
+ graph.getNodes().filter((node) => !boundaryIds.includes(node.id)).map((node) => ({
+ id: node.id, ...node.getPosition(), ...node.getSize(),
+ })),
+ graph.getEdges().map((edge) => ({ id: edge.id, source: edge.getSourceCellId(), target: edge.getTargetCellId() })),
+ )
+ : null;
for (const edge of graph.getEdges()) {
const source = edge.getSourceNode();
const target = edge.getTargetNode();
@@ -1385,8 +1396,13 @@ const applyOrthogonalEdgePorts = (graph: Graph, kind: DiagramDocument["kind"]) =
const ports = kind === "architecture"
? architectureEdgePorts(sourceBox, targetBox)
: flowchartEdgePorts(sourceBox, targetBox);
- edge.setSource({ cell: source.id, port: ports.source });
- edge.setTarget({ cell: target.id, port: ports.target });
+ const terminal = architectureTerminals?.get(edge.id);
+ edge.setSource(terminal
+ ? { cell: source.id, anchor: architectureTerminalAnchor(terminal.source) }
+ : { cell: source.id, port: ports.source });
+ edge.setTarget(terminal
+ ? { cell: target.id, anchor: architectureTerminalAnchor(terminal.target) }
+ : { cell: target.id, port: ports.target });
edge.setRouter(kind === "architecture"
? architectureEdgeRouter(source.id, target.id, boundaryIds, ports)
: flowchartEdgeIsStraight(sourceBox, targetBox) ? { name: "normal" } : FLOWCHART_EDGE_ROUTER);
@@ -2014,6 +2030,16 @@ export const DiagramEditorPane = ({
showNodeSelectionBox: true,
showEdgeSelectionBox: true,
}));
+ let relationHover: { type: "node" | "edge"; id: string } | null = null;
+ let relationSelection: { type: "node" | "edge"; id: string } | null = null;
+ const refreshRelationFocus = () => {
+ if (document.kind === "architecture") {
+ focusArchitectureRelations(graph, containerRef.current, relationHover ?? relationSelection);
+ }
+ };
+ if (document.kind === "architecture") {
+ graph.on("render:done", refreshRelationFocus);
+ }
graph.addNodes(document.nodes.map((node) => {
const inferredResourceIcon = document.kind === "architecture" && !node.resourceIcon
? inferArchitectureResourceIcon(node.label, t)
@@ -2032,6 +2058,25 @@ export const DiagramEditorPane = ({
}
graph.addEdges(document.edges.map((edge) => edgeMetadata(edge, document.kind, documentTheme, appearance, documentStructure)));
if (usesOrthogonalDiagramEdges(document.kind)) applyOrthogonalEdgePorts(graph, document.kind);
+ if (document.kind === "architecture") {
+ graph.on("node:mouseenter", ({ node }: { node: Node }) => {
+ if (node.getData<NodeData>()?.shape === "boundary") return;
+ relationHover = { type: "node", id: node.id };
+ refreshRelationFocus();
+ });
+ graph.on("node:mouseleave", ({ node }: { node: Node }) => {
+ if (relationHover?.type === "node" && relationHover.id === node.id) relationHover = null;
+ refreshRelationFocus();
+ });
+ graph.on("edge:mouseenter", ({ edge }: { edge: Edge }) => {
+ relationHover = { type: "edge", id: edge.id };
+ refreshRelationFocus();
+ });
+ graph.on("edge:mouseleave", ({ edge }: { edge: Edge }) => {
+ if (relationHover?.type === "edge" && relationHover.id === edge.id) relationHover = null;
+ refreshRelationFocus();
+ });
+ }
applyGraphPalette(graph, documentTheme, document.kind, appearance, documentStructure);
graph.on("scale", () => setZoomPercent(Math.round(graph.scale().sx * 100)));
graph.cleanHistory();
@@ -2087,6 +2132,9 @@ export const DiagramEditorPane = ({
updateHistory();
};
const clearSelectionAfterHistory = () => {
+ relationSelection = null;
+ relationHover = null;
+ refreshRelationFocus();
refreshArchitecturePorts();
applyGraphPalette(graph, themeRef.current, document.kind, appearanceRef.current, structureRef.current);
graph.cleanSelection();
@@ -2113,6 +2161,10 @@ export const DiagramEditorPane = ({
});
graph.on("node:click", ({ node }: { node: Node }) => {
const data = node.getData<NodeData>();
+ relationSelection = document.kind === "architecture" && data?.shape !== "boundary"
+ ? { type: "node", id: node.id }
+ : null;
+ refreshRelationFocus();
dismissFlowQuickCreate();
if (isConnectableDiagram(document.kind)) setOnlyFlowNodePortsActive(graph, node);
containerRef.current?.focus({ preventScroll: true });
@@ -2138,6 +2190,8 @@ export const DiagramEditorPane = ({
}
});
graph.on("edge:click", ({ edge }: { edge: Edge }) => {
+ relationSelection = { type: "edge", id: edge.id };
+ refreshRelationFocus();
dismissFlowQuickCreate();
if (isConnectableDiagram(document.kind)) setOnlyFlowNodePortsActive(graph);
setSelectedNodeId(null);
@@ -2147,6 +2201,9 @@ export const DiagramEditorPane = ({
setHasSelection(true);
});
graph.on("blank:click", () => {
+ relationSelection = null;
+ relationHover = null;
+ refreshRelationFocus();
dismissFlowQuickCreate();
if (isConnectableDiagram(document.kind)) setOnlyFlowNodePortsActive(graph);
setSelectedNodeId(null);
@@ -2156,6 +2213,9 @@ export const DiagramEditorPane = ({
setHasSelection(false);
});
graph.on("edge:removed", ({ edge }: { edge: Edge }) => {
+ if (relationSelection?.type === "edge" && relationSelection.id === edge.id) relationSelection = null;
+ if (relationHover?.type === "edge" && relationHover.id === edge.id) relationHover = null;
+ refreshRelationFocus();
const draft = edge.getData<{ quickConnectDraft?: boolean; restoreHistory?: boolean }>();
if (flowQuickCreateRef.current?.draftEdgeId === edge.id) {
flowQuickCreateRef.current = null;
@@ -2163,6 +2223,11 @@ export const DiagramEditorPane = ({
}
if (draft?.quickConnectDraft && draft.restoreHistory) graph.enableHistory();
});
+ graph.on("node:removed", ({ node }: { node: Node }) => {
+ if (relationSelection?.type === "node" && relationSelection.id === node.id) relationSelection = null;
+ if (relationHover?.type === "node" && relationHover.id === node.id) relationHover = null;
+ refreshRelationFocus();
+ });
const showFlowQuickCreate = (
edge: Edge,
sourceNodeId: string,
@@ -2435,6 +2500,7 @@ export const DiagramEditorPane = ({
));
});
return () => {
+ if (containerRef.current) delete containerRef.current.dataset.relationsFocused;
containerRef.current?.removeEventListener("pointerdown", handleFlowPointerDown, true);
window.removeEventListener("pointerup", handleFlowPointerUp, true);
flowPointerDragRef.current = null;
diff --git a/apps/web/src/lib/architecture-relations.ts b/apps/web/src/lib/architecture-relations.ts
new file mode 100644
index 00000000..96ad2c09
--- /dev/null
+++ b/apps/web/src/lib/architecture-relations.ts
@@ -0,0 +1,27 @@
+import { Graph } from "@antv/x6";
+
+export const focusArchitectureRelations = (
+ graph: Graph,
+ host: HTMLElement | null,
+ focus: { type: "node" | "edge"; id: string } | null,
+) => {
+ if (!host) return;
+ host.dataset.relationsFocused = focus ? "true" : "false";
+ const focusedEdges = new Set(graph.getEdges().filter((edge) => focus && (focus.type === "edge"
+ ? edge.id === focus.id
+ : edge.getSourceCellId() === focus.id || edge.getTargetCellId() === focus.id)).map((edge) => edge.id));
+ const focusedNodes = new Set<string>();
+ if (focus?.type === "node") focusedNodes.add(focus.id);
+ for (const edge of graph.getEdges()) {
+ if (focusedEdges.has(edge.id)) {
+ focusedNodes.add(edge.getSourceCellId());
+ focusedNodes.add(edge.getTargetCellId());
+ }
+ graph.findViewByCell(edge)?.container.classList.toggle("edgeever-relation-focused", focusedEdges.has(edge.id));
+ }
+ for (const node of graph.getNodes()) {
+ const container = graph.findViewByCell(node)?.container;
+ container?.classList.toggle("edgeever-relation-focused", focusedNodes.has(node.id));
+ container?.classList.toggle("edgeever-relation-boundary", node.getData<{ shape?: string }>()?.shape === "boundary");
+ }
+};
diff --git a/apps/web/src/styles/globals.css b/apps/web/src/styles/globals.css
index 70931e7e..d5f008aa 100644
--- a/apps/web/src/styles/globals.css
+++ b/apps/web/src/styles/globals.css
@@ -715,6 +715,18 @@ html[data-edgeever-extension-theme] .edgeever-memo-divider {
box-shadow: inset 0 0 0 2px rgb(var(--brand-green-rgb) / 0.5);
}
+.edgeever-diagram-canvas[data-diagram-kind="architecture"][data-relations-focused="true"] .x6-edge:not(.edgeever-relation-focused) {
+ opacity: 0.12;
+}
+
+.edgeever-diagram-canvas[data-diagram-kind="architecture"][data-relations-focused="true"] .x6-node:not(.edgeever-relation-focused):not(.edgeever-relation-boundary) {
+ opacity: 0.4;
+}
+
+.edgeever-diagram-canvas[data-diagram-kind="architecture"][data-relations-focused="true"] .x6-edge.edgeever-relation-focused {
+ filter: drop-shadow(0 0 3px rgb(22 160 110 / 0.22));
+}
+
/* X6 owns the scroll extent so oversized diagrams remain reachable in both
* directions while the editor chrome stays fixed around the viewport. */
.edgeever-diagram-scroller {
diff --git a/packages/shared/src/diagram-architecture-style.test.mjs b/packages/shared/src/diagram-architecture-style.test.mjs
index 53af8023..e7c83eb5 100644
--- a/packages/shared/src/diagram-architecture-style.test.mjs
+++ b/packages/shared/src/diagram-architecture-style.test.mjs
@@ -8,6 +8,8 @@ import {
ARCHITECTURE_SURFACES,
architectureEdgePorts,
architectureEdgeRouter,
+ architectureEdgeTerminals,
+ architectureTerminalAnchor,
architectureEdgeVisual,
architectureIconElements,
architectureMermaidClassDefs,
@@ -64,6 +66,25 @@ describe("architecture semantic paint", () => {
expect(router.args.endDirections).toEqual(["right"]);
});
+ test("fans out connections in opposite-node order on a shared face", () => {
+ const nodes = [
+ { id: "hub", x: 100, y: 100, width: 156, height: 64 },
+ { id: "upper", x: 420, y: 0, width: 156, height: 64 },
+ { id: "middle", x: 420, y: 100, width: 156, height: 64 },
+ { id: "lower", x: 420, y: 200, width: 156, height: 64 },
+ ];
+ const terminals = architectureEdgeTerminals(nodes, [
+ { id: "lower-edge", source: "hub", target: "lower" },
+ { id: "upper-edge", source: "hub", target: "upper" },
+ { id: "middle-edge", source: "hub", target: "middle" },
+ ]);
+ expect(terminals.get("upper-edge")?.source).toEqual({ side: "right", offset: -16 });
+ expect(terminals.get("middle-edge")?.source).toEqual({ side: "right", offset: 0 });
+ expect(terminals.get("lower-edge")?.source).toEqual({ side: "right", offset: 16 });
+ expect(architectureTerminalAnchor(terminals.get("upper-edge").source)).toEqual({ name: "right", args: { dy: -16 } });
+ expect(terminals.get("upper-edge")?.target.offset).toBe(0);
+ });
+
test("keeps every component fill distinct in light and dark", () => {
for (const appearance of ["light", "dark"]) {
const fills = ARCHITECTURE_COMPONENT_SHAPES.map((shape) => resolveArchitectureSurface(appearance).nodes[shape].fill);
diff --git a/packages/shared/src/diagram-architecture-style.ts b/packages/shared/src/diagram-architecture-style.ts
index c6f36ea0..d584b5f8 100644
--- a/packages/shared/src/diagram-architecture-style.ts
+++ b/packages/shared/src/diagram-architecture-style.ts
@@ -71,6 +71,63 @@ export const architectureEdgePorts = (
: { source: "top", target: "bottom" };
};
+export type ArchitectureEdgeTerminal = { side: ArchitectureEdgePortName; offset: number };
+
+export const architectureTerminalAnchor = ({ side, offset }: ArchitectureEdgeTerminal) => ({
+ name: side,
+ args: side === "left" || side === "right" ? { dy: offset } : { dx: offset },
+});
+
+/** Spread edges on a node face so separate relationships do not leave through one point. */
+export const architectureEdgeTerminals = (
+ nodes: Array<ArchitectureEdgeBox & { id: string }>,
+ edges: Array<{ id: string; source: string; target: string }>,
+) => {
+ const nodeById = new Map(nodes.map((node) => [node.id, node]));
+ const terminals = new Map<string, { source: ArchitectureEdgeTerminal; target: ArchitectureEdgeTerminal }>();
+ const faces = new Map<string, Array<{ edgeId: string; end: "source" | "target"; opposite: number }>>();
+ for (const edge of edges) {
+ const source = nodeById.get(edge.source);
+ const target = nodeById.get(edge.target);
+ if (!source || !target) continue;
+ const ports = architectureEdgePorts(source, target);
+ terminals.set(edge.id, {
+ source: { side: ports.source, offset: 0 },
+ target: { side: ports.target, offset: 0 },
+ });
+ for (const [end, node, side, oppositeNode] of [
+ ["source", source, ports.source, target],
+ ["target", target, ports.target, source],
+ ] as const) {
+ const key = `${node.id}:${side}`;
+ const face = faces.get(key) ?? [];
+ face.push({
+ edgeId: edge.id,
+ end,
+ opposite: side === "left" || side === "right"
+ ? oppositeNode.y + oppositeNode.height / 2
+ : oppositeNode.x + oppositeNode.width / 2,
+ });
+ faces.set(key, face);
+ }
+ }
+ for (const [key, face] of faces) {
+ if (face.length < 2) continue;
+ const separator = key.lastIndexOf(":");
+ const node = nodeById.get(key.slice(0, separator));
+ const side = key.slice(separator + 1);
+ if (!node) continue;
+ const length = side === "left" || side === "right" ? node.height : node.width;
+ const span = Math.min(Math.max(0, length - 28), (face.length - 1) * 16);
+ face.sort((a, b) => a.opposite - b.opposite || a.edgeId.localeCompare(b.edgeId));
+ face.forEach(({ edgeId, end }, index) => {
+ const terminal = terminals.get(edgeId);
+ if (terminal) terminal[end].offset = Math.round(-span / 2 + span * index / (face.length - 1));
+ });
+ }
+ return terminals;
+};
+
export type ArchitectureComponentShape = Exclude<
DiagramNodeShape,
"topic" | "process" | "decision" | "terminator" | "boundary"
diff --git a/packages/shared/src/diagram-view.ts b/packages/shared/src/diagram-view.ts
index d9c03e88..4ebc7360 100644
--- a/packages/shared/src/diagram-view.ts
+++ b/packages/shared/src/diagram-view.ts
@@ -4,7 +4,9 @@ import {
ARCHITECTURE_EDGE_LABEL_LINE_HEIGHT,
ARCHITECTURE_LABEL_FONT,
architectureEdgePorts,
+ architectureEdgeTerminals,
architectureEdgeRouter,
+ architectureTerminalAnchor,
architectureEdgeVisual,
architectureNodeVisual,
resolveArchitectureSurface,
@@ -149,6 +151,9 @@ export const diagramDocumentToX6Cells = (
});
const projectedById = new Map(nodes.map((node) => [node.id, node]));
const architectureBoundaryIds = document.nodes.filter((node) => node.shape === "boundary").map((node) => node.id);
+ const architectureTerminals = document.kind === "architecture"
+ ? architectureEdgeTerminals(document.nodes.filter((node) => node.shape !== "boundary"), document.edges)
+ : null;
const edges = document.edges.map((edge) => {
const edgeKind = edge.kind ?? (document.kind === "architecture" ? "dependency" : undefined);
const sourceNode = projectedById.get(edge.source);
@@ -187,15 +192,20 @@ export const diagramDocumentToX6Cells = (
: null;
const orthogonalStraight = document.kind === "flowchart"
&& Boolean(orthogonalPorts && sourceNode && targetNode && flowchartEdgeIsStraight(sourceNode, targetNode));
+ const architectureTerminal = architectureTerminals?.get(edge.id);
return {
id: edge.id,
source: document.kind === "mind-map"
? { cell: edge.source, ...(sourceTerminal ?? { anchor: { name: sides.source } }) }
+ : architectureTerminal
+ ? { cell: edge.source, anchor: architectureTerminalAnchor(architectureTerminal.source) }
: orthogonalPorts
? { cell: edge.source, port: orthogonalPorts.source }
: { cell: edge.source },
target: document.kind === "mind-map"
? { cell: edge.target, ...(targetTerminal ?? { anchor: { name: sides.target } }) }
+ : architectureTerminal
+ ? { cell: edge.target, anchor: architectureTerminalAnchor(architectureTerminal.target) }
: orthogonalPorts
? { cell: edge.target, port: orthogonalPorts.target }
: { cell: edge.target },
diff --git a/packages/shared/src/diagram.test.mjs b/packages/shared/src/diagram.test.mjs
index 8f1fab01..fee9c9fd 100644
--- a/packages/shared/src/diagram.test.mjs
+++ b/packages/shared/src/diagram.test.mjs
@@ -181,7 +181,7 @@ describe("diagram document", () => {
expect(fallback).toContain("classDef archDatabase");
});
- test("projects forward diagonal architecture edges through horizontal ports", () => {
+ test("projects forward diagonal architecture edges through horizontal anchors", () => {
const document = createDefaultDiagramDocument("architecture");
const edge = document.edges[0];
const source = document.nodes.find((node) => node.id === edge.source);
@@ -190,8 +190,8 @@ describe("diagram document", () => {
Object.assign(target, { x: 446, y: 658, width: 170, height: 68 });
const projectedEdge = diagramDocumentToX6Cells(document, "light").edges[0];
- expect(projectedEdge.source.port).toBe("right");
- expect(projectedEdge.target.port).toBe("left");
+ expect(projectedEdge.source.anchor.name).toBe("right");
+ expect(projectedEdge.target.anchor.name).toBe("left");
});
test("routes aligned architecture edges around intervening components", () => {
@@ -207,8 +207,8 @@ describe("diagram document", () => {
expect(edge.router.name).toBe("manhattan");
expect(edge.router.args.excludeNodes).toContain("system");
expect(edge.router.args.excludeNodes).not.toContain("database");
- expect(edge.router.args.startDirections).toEqual([edge.source.port]);
- expect(edge.router.args.endDirections).toEqual([edge.target.port]);
+ expect(edge.router.args.startDirections).toEqual([edge.source.anchor.name]);
+ expect(edge.router.args.endDirections).toEqual([edge.target.anchor.name]);
});
test("projects architecture edge labels below component typography", () => {
@@ -246,8 +246,8 @@ describe("diagram document", () => {
expect(dark.nodes.find((node) => node.id === "api").attrs.body.fill).not.toBe(
dark.nodes.find((node) => node.id === "database").attrs.body.fill,
);
- expect(projected.edges[0].source.port).toBeDefined();
- expect(projected.edges[0].target.port).toBeDefined();
+ expect(projected.edges[0].source.anchor.name).toBeDefined();
+ expect(projected.edges[0].target.anchor.name).toBeDefined();
expect(["normal", "manhattan"]).toContain(projected.edges[0].router.name);
});