Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

fix: straighten singly spread architecture links

tt-a1ib204f7360800
diff --git a/archify.zip b/archify.zip
index c2b9ffdf..7550b57a 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index ee784425..3d66674f 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -70,7 +70,7 @@ Read Mermaid for topology and meaning, then author fresh Archify JSON; do not me
- Component types are `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, and `external`; variants are `default`, `emphasis`, `security`, and `dashed`.
- Spacing means clear gap, not center distance. For a relationship label, clear gap must exceed its measured mask width; otherwise omit the label or move it deliberately.
- Automatic routes own their endpoint sides. A side is a direction contract: the first and final segment must leave/enter perpendicular to that side.
-- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps a lone, unobstructed pair of automatic left/right ports on one horizontal axis when their midpoint offset is under 16px and both ports retain corner clearance.
+- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle. It skips single relationships and explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes. Near parallel ports use an outside bridge so automatic routing cannot create a sub-8px segment or sub-16px interior turn. Architecture separately keeps unobstructed facing automatic ports (`left`/`right` or `top`/`bottom`) on one shared axis when their offset is under 16px and both ports retain corner clearance. If exactly one endpoint was spread, only the unshared endpoint may move onto that axis; if both endpoints were spread, keep the outside bridge so competing ports remain distinct.
- Never accept an edge crossing an unrelated opaque node, an ambiguous shared corridor, or a relationship label masking another route.
Read `references/authoring-contract.md` only when you need field enums, spacing math, geometry repair rules, repository evidence, or mode-specific placement.
diff --git a/archify/references/authoring-contract.md b/archify/references/authoring-contract.md
index 3c32e95b..32f1712b 100644
--- a/archify/references/authoring-contract.md
+++ b/archify/references/authoring-contract.md
@@ -64,7 +64,7 @@ in the generated viewer.
## Executable geometry rules
-- Node anchors start at side midpoints. `left`/`right` change the horizontal endpoint; `top`/`bottom` change the vertical endpoint. For one fully automatic Architecture relationship, unobstructed left/right ports whose midpoint offset is under 16px may share one horizontal axis when both endpoints retain the 16px corner gutter.
+- Node anchors start at side midpoints. `left`/`right` change the horizontal endpoint; `top`/`bottom` change the vertical endpoint. For an automatic Architecture relationship, unobstructed facing ports whose axis offset is under 16px may share one horizontal or vertical axis when both endpoints retain the 16px corner gutter. If exactly one endpoint belongs to a spread group, only its unshared counterpart moves; relationships spread at both endpoints keep their distinct ports and outside bridge.
- A side is a direction contract. The first and final route segment must be perpendicular and outward/inward in the named direction.
- Automatic Port Spread is a default renderer behavior for architecture, workflow, data-flow, and lifecycle diagrams. Shared automatic endpoints spread deterministically and symmetrically with a 16px corner gutter. It does not apply to sequence messages, single relationships, or explicit `via`, `channelX`, `channelY`, `labelAt`, or non-`auto` routes.
- Showcase route rhythm: every nonzero segment must be at least 8px; every interior segment must be at least 16px. When spread ports are nearly parallel, the router uses a 24px endpoint stub and a 16px outside bridge instead of manufacturing a tiny dogleg.
diff --git a/archify/renderers/architecture/render-architecture.mjs b/archify/renderers/architecture/render-architecture.mjs
index 1d414f90..02eb0c8f 100644
--- a/archify/renderers/architecture/render-architecture.mjs
+++ b/archify/renderers/architecture/render-architecture.mjs
@@ -479,35 +479,65 @@ const AUTOMATIC_PORT_CORNER_GUTTER = 16;
const AUTOMATIC_PORT_ALIGNMENT_DELTA = 16;
function portHasCornerClearance(rect, side, point) {
- if (side !== 'left' && side !== 'right') return false;
- const inset = Math.min(AUTOMATIC_PORT_CORNER_GUTTER, rect.height / 2);
- return point[1] >= rect.y + inset && point[1] <= rect.y + rect.height - inset;
+ if (side === 'left' || side === 'right') {
+ const inset = Math.min(AUTOMATIC_PORT_CORNER_GUTTER, rect.height / 2);
+ return point[1] >= rect.y + inset && point[1] <= rect.y + rect.height - inset;
+ }
+ if (side === 'top' || side === 'bottom') {
+ const inset = Math.min(AUTOMATIC_PORT_CORNER_GUTTER, rect.width / 2);
+ return point[0] >= rect.x + inset && point[0] <= rect.x + rect.width - inset;
+ }
+ return false;
}
-function alignUnspreadFacingPorts(conn, from, to, start, end, fromSide, toSide) {
+function alignFacingPorts(conn, from, to, start, end, fromSide, toSide, ports) {
const hasExplicitGeometry = (
conn.via
|| (conn.route && conn.route !== 'auto')
|| conn.channelX !== undefined
|| conn.channelY !== undefined
|| conn.labelAt
- || (conn.fromSide && conn.fromSide !== 'auto')
- || (conn.toSide && conn.toSide !== 'auto')
);
const horizontallyFacing = (
(fromSide === 'right' && toSide === 'left')
|| (fromSide === 'left' && toSide === 'right')
);
- if (hasExplicitGeometry || !horizontallyFacing) return { start, end };
- if (Math.abs(start[1] - end[1]) >= AUTOMATIC_PORT_ALIGNMENT_DELTA) return { start, end };
-
- // A lone near-aligned edge does not need the outside bridge reserved for
- // genuinely spread ports. Keep one shared flow axis when the opposite
- // side can accept that port with the same 16px corner clearance.
- const candidates = [
- { start, end: [end[0], start[1]] },
- { start: [start[0], end[1]], end },
- ];
+ const verticallyFacing = (
+ (fromSide === 'bottom' && toSide === 'top')
+ || (fromSide === 'top' && toSide === 'bottom')
+ );
+ if (hasExplicitGeometry || (!horizontallyFacing && !verticallyFacing)) return { start, end };
+
+ const fromSpread = Boolean(ports?.from);
+ const toSpread = Boolean(ports?.to);
+ if (fromSpread && toSpread) return { start, end };
+ const hasExplicitSides = (
+ (conn.fromSide && conn.fromSide !== 'auto')
+ || (conn.toSide && conn.toSide !== 'auto')
+ );
+ if (!fromSpread && !toSpread && hasExplicitSides) return { start, end };
+
+ const alignmentDelta = horizontallyFacing
+ ? Math.abs(start[1] - end[1])
+ : Math.abs(start[0] - end[0]);
+ if (alignmentDelta >= AUTOMATIC_PORT_ALIGNMENT_DELTA) return { start, end };
+
+ // Keep the shared endpoint's distinct spread slot and move only the
+ // relationship's unshared endpoint onto that axis. With no spread endpoint,
+ // retain the existing least-movement choice between the two facing sides.
+ // If both endpoints are shared, preserve the outside bridge so no competing
+ // port is silently collapsed.
+ const alignEndToStart = horizontallyFacing
+ ? { start, end: [end[0], start[1]] }
+ : { start, end: [start[0], end[1]] };
+ const alignStartToEnd = horizontallyFacing
+ ? { start: [start[0], end[1]], end }
+ : { start: [end[0], start[1]], end };
+ const candidates = fromSpread
+ ? [alignEndToStart]
+ : toSpread
+ ? [alignStartToEnd]
+ : [alignEndToStart, alignStartToEnd];
for (const candidate of candidates) {
const points = [candidate.start, candidate.end];
if (portHasCornerClearance(from, fromSide, candidate.start)
@@ -644,9 +674,16 @@ function pathFor(conn) {
const { fromSide, toSide } = connectionSides(conn);
const baseStart = ports?.from || anchor(from, fromSide);
const baseEnd = ports?.to || anchor(to, toSide);
- const { start, end } = ports
- ? { start: baseStart, end: baseEnd }
- : alignUnspreadFacingPorts(conn, from, to, baseStart, baseEnd, fromSide, toSide);
+ const { start, end } = alignFacingPorts(
+ conn,
+ from,
+ to,
+ baseStart,
+ baseEnd,
+ fromSide,
+ toSide,
+ ports,
+ );
const points = [start, ...routeVia(conn, from, to, start, end, fromSide, toSide), end];
const routed = { d: roundedPath(points, 8), points };
pathCache.set(conn, routed);
diff --git a/archify/test/automatic-port-spread.test.mjs b/archify/test/automatic-port-spread.test.mjs
index d4127adb..f7013e53 100644
--- a/archify/test/automatic-port-spread.test.mjs
+++ b/archify/test/automatic-port-spread.test.mjs
@@ -78,7 +78,7 @@ test('architecture: automatic port assignment is stable when relationship input
}
});
-test('architecture: automatic port spread avoids micro-stubs when a target stays centered above the source', () => {
+test('architecture: a singly spread near-aligned vertical relationship keeps one direct axis', () => {
const html = render('architecture', {
schema_version: 1,
diagram_type: 'architecture',
@@ -94,14 +94,131 @@ test('architecture: automatic port spread avoids micro-stubs when a target stays
],
});
- assert.deepEqual(connectionPoints(html, 'read'), [
- [742, 300],
- [742, 276],
- [758, 276],
- [758, 204],
- [735, 204],
- [735, 180],
- ]);
+ assert.deepEqual(connectionPoints(html, 'read'), [[742, 300], [742, 180]]);
+ assert.notDeepEqual(connectionPoints(html, 'verify')[0], connectionPoints(html, 'read')[0]);
+});
+
+test('architecture: a singly spread near-aligned horizontal relationship keeps one direct axis', () => {
+ const html = render('architecture', {
+ schema_version: 1,
+ diagram_type: 'architecture',
+ meta: { title: 'Near-aligned horizontal fan-out' },
+ components: [
+ { id: 'hub', type: 'backend', label: 'Hub', pos: [100, 100], size: [120, 60] },
+ { id: 'direct', type: 'database', label: 'Direct', pos: [500, 107], size: [120, 60] },
+ { id: 'branch', type: 'cloud', label: 'Branch', pos: [500, 300], size: [120, 60] },
+ ],
+ connections: [
+ { id: 'hub-direct', from: 'hub', to: 'direct', fromSide: 'right', toSide: 'left' },
+ { id: 'hub-branch', from: 'hub', to: 'branch', fromSide: 'right', toSide: 'left' },
+ ],
+ });
+
+ assert.deepEqual(connectionPoints(html, 'hub-direct'), [[220, 123], [500, 123]]);
+ assert.notDeepEqual(connectionPoints(html, 'hub-branch')[0], connectionPoints(html, 'hub-direct')[0]);
+});
+
+test('architecture: a shared bottom port keeps its aligned child relationship straight', () => {
+ const doc = {
+ schema_version: 1,
+ diagram_type: 'architecture',
+ meta: { title: 'Vertical child relationship' },
+ components: [
+ { id: 'parent', type: 'backend', label: 'Parent Session', pos: [300, 100], size: [200, 60] },
+ { id: 'terminal', type: 'backend', label: 'Background terminal', pos: [300, 300], size: [200, 60] },
+ { id: 'workflow', type: 'backend', label: 'Workflow', pos: [560, 300], size: [180, 60] },
+ ],
+ connections: [
+ { id: 'parent-terminal', from: 'parent', to: 'terminal', fromSide: 'bottom', toSide: 'top' },
+ { id: 'parent-workflow', from: 'parent', to: 'workflow', fromSide: 'bottom', toSide: 'top' },
+ ],
+ };
+ const forward = render('architecture', doc);
+ const reversed = render('architecture', {
+ ...doc,
+ connections: [...doc.connections].reverse(),
+ });
+
+ assert.deepEqual(connectionPoints(forward, 'parent-terminal'), [[393, 160], [393, 300]]);
+ assert.notDeepEqual(
+ connectionPoints(forward, 'parent-workflow')[0],
+ connectionPoints(forward, 'parent-terminal')[0],
+ );
+ for (const connection of doc.connections) {
+ assert.deepEqual(
+ connectionPoints(forward, connection.id),
+ connectionPoints(reversed, connection.id),
+ `${connection.id} moved after input reordering`,
+ );
+ }
+});
+
+test('architecture: incoming and outgoing relationships keep distinct bottom ports while the direct child stays straight', () => {
+ const html = render('architecture', {
+ schema_version: 1,
+ diagram_type: 'architecture',
+ meta: { title: 'Shared incoming and outgoing side' },
+ components: [
+ { id: 'workflow', type: 'backend', label: 'Workflow', pos: [80, 320], size: [180, 60] },
+ { id: 'child', type: 'security', label: 'Child boundary', pos: [300, 100], size: [200, 60] },
+ { id: 'footer', type: 'frontend', label: 'Footer', pos: [300, 320], size: [200, 60] },
+ ],
+ connections: [
+ { id: 'workflow-child', from: 'workflow', to: 'child', fromSide: 'right', toSide: 'bottom' },
+ { id: 'child-footer', from: 'child', to: 'footer', fromSide: 'bottom', toSide: 'top' },
+ ],
+ });
+
+ assert.deepEqual(connectionPoints(html, 'child-footer'), [[407, 160], [407, 320]]);
+ assert.notDeepEqual(
+ connectionPoints(html, 'workflow-child').at(-1),
+ connectionPoints(html, 'child-footer')[0],
+ );
+});
+
+test('architecture: a near-aligned relationship keeps the outside bridge when both endpoints are spread', () => {
+ const html = render('architecture', {
+ schema_version: 1,
+ diagram_type: 'architecture',
+ meta: { title: 'Two-sided port competition' },
+ components: [
+ { id: 'source', type: 'backend', label: 'Source', pos: [300, 320], size: [160, 60] },
+ { id: 'source-peer', type: 'backend', label: 'Source peer', pos: [80, 320], size: [160, 60] },
+ { id: 'target', type: 'database', label: 'Target', pos: [300, 100], size: [160, 60] },
+ { id: 'target-peer', type: 'database', label: 'Target peer', pos: [560, 100], size: [160, 60] },
+ ],
+ connections: [
+ { id: 'source-target', from: 'source', to: 'target', fromSide: 'top', toSide: 'bottom' },
+ { id: 'source-peer-target', from: 'source-peer', to: 'target', fromSide: 'top', toSide: 'bottom' },
+ { id: 'source-target-peer', from: 'source', to: 'target-peer', fromSide: 'top', toSide: 'bottom' },
+ ],
+ });
+
+ const points = connectionPoints(html, 'source-target');
+ assert.ok(points.length > 2);
+ assert.notEqual(points[0][0], points.at(-1)[0]);
+});
+
+test('architecture: a singly spread near-aligned relationship keeps the bridge when its direct axis is blocked', () => {
+ const html = render('architecture', {
+ schema_version: 1,
+ diagram_type: 'architecture',
+ meta: { title: 'Blocked vertical axis' },
+ components: [
+ { id: 'parent', type: 'backend', label: 'Parent', pos: [300, 100], size: [200, 60] },
+ { id: 'terminal', type: 'backend', label: 'Terminal', pos: [300, 400], size: [200, 60] },
+ { id: 'workflow', type: 'backend', label: 'Workflow', pos: [560, 400], size: [180, 60] },
+ { id: 'obstacle', type: 'external', label: 'X', pos: [382, 245], size: [26, 60] },
+ ],
+ connections: [
+ { id: 'parent-terminal', from: 'parent', to: 'terminal', fromSide: 'bottom', toSide: 'top' },
+ { id: 'parent-workflow', from: 'parent', to: 'workflow', fromSide: 'bottom', toSide: 'top' },
+ ],
+ });
+
+ const points = connectionPoints(html, 'parent-terminal');
+ assert.ok(points.length > 2);
+ assert.notEqual(points[0][0], points.at(-1)[0]);
});
test('architecture: single and explicitly positioned relationships keep legacy anchors', () => {
@@ -246,10 +363,10 @@ test('skill and READMEs describe automatic port spread as bounded default behavi
assert.match(skill, /Automatic Port Spread is a default renderer behavior/);
assert.match(skill, /single relationship|single relationships/);
assert.match(skill, /explicit `via`.*`channelX`.*`channelY`.*`labelAt`/);
- assert.match(skill, /lone, unobstructed pair of automatic left\/right ports on one horizontal axis/);
+ assert.match(skill, /facing automatic ports \(`left`\/`right` or `top`\/`bottom`\).*one shared axis/);
const authoringContract = fs.readFileSync(path.join(skillRoot, 'references/authoring-contract.md'), 'utf8');
- assert.match(authoringContract, /unobstructed left\/right ports.*may share one horizontal axis/);
+ assert.match(authoringContract, /unobstructed facing ports.*may share one horizontal or vertical axis/);
const repoRoot = path.resolve(skillRoot, '..');
for (const file of ['README.md', 'README_EN.md']) {