Skip to main content

Dense Architecture Diagram Layout

Hub-and-spoke diagrams that must pass strict lint. Sparse diagrams (6-7 nodes, one main spine, a few side branches — like the RenewalRadar example) validate almost first-try. The hard case is a dense hub: many components whose edges all fan into a single central service (e.g. one Worker receiving from and sending to 6+ providers). That topology will NOT route cleanly on the first draft. This skill is the converging method.

The fundamental rule that ends most wasted iterations​

Auto-route first. Do not add fromSide/toSide/via/labelAt until the validator flags a specific problem — then add exactly one diagnosed control per repair.

In Archify, "Automatic routes own their endpoint sides." Adding explicit sides/vias preemptively causes more errors than it fixes (endpoint-side-direction, micro-segments, crossings), because the renderer's Automatic Port Spread + outside-bridge logic is what handles near-parallel hubs. Every regression this skill was born from came from hand-routing too early.

If you must use an explicit fromSide + via (the dense-hub exception)​

Orthogonal routing is strict about the FIRST and FINAL segments being perpendicular to their declared side:

  • fromSide: "top" → the first via point must lie directly above the source port at the SAME x. fromSide:"bottom" → directly below, same x. "left"/"right" → same y.
  • The FINAL segment must enter the target side perpendicular. Set the last via so it shares the target's axis (e.g. for a left entry into the central node, the last via's y must equal the port's y, producing a pure-horizontal final segment). A single misaligned via produces a diagonal last segment → artifact/orthogonal-arrows failure.
  • Ports sit at side midpoints. So a node at [520,640] size [150,60] has top-center at [595,640]; a fromSide:"top" first via must be [595, ...above], not a stray x.

Placement strategies that make dense hubs route​

  • Keep the happy-path spine left-to-right and push the hub to one side of it. One obvious main path; side branches leave the nearest main-path node.
  • Delivery/send providers side-by-side (same row), never stacked in one column. Two stacked providers both drawing a vertical edge down to a customer will cross the sibling. Spread them horizontally so each fan-out/down edge has its own corridor.
  • Inbound webhook providers (Stripe, Square, etc.) belong in a region cleared of the storage cluster, routed via a lane that runs below/around the DB+Auth boxes — otherwise their up-edges thread straight through the storage group.
  • Reserve > label-width + 8px of clear gap between nodes that carry a labeled edge. If a label (e.g. "opens /r/:token") can't fit the gap, MOVE the nodes farther apart rather than shrinking/stacking.
  • Keep external actors outside the system boundary region when factually true.

The converging repair loop (stop guessing layout)​

Run validate --quality showcase --json after EVERY single edit. Consume diagnostics by code / subject / measured evidence, and use the exact labelAt / labelDy the diagnostic suggests rather than estimating new offsets. Repair in this order (from the authoring contract):

  1. schema / missing meta.quality_profile → 2. node overlap / out-of-range → 3. edge-through-node + endpoint-direction → 4. crossings / ambiguous corridors / border runs / segment rhythm → 5. label overlaps & clearances.

Objective rule: if the error count is not at a new minimum after two consecutive rounds, your LAYOUT is wrong — stop tuning vias and redo the lane placement (this session: 33→20→19→15, then a bad hand-route jumped to 27→31, and recovery came from reverting to clean lane-based layout + stripping bad vias).

Ownership/boundary gotchas​

  • engineering_profile: "deployment-ownership" adds strict checks: a security-group (private boundary) must wrap components from exactly one shared region, and a stateful component (database) must sit inside a private security-group. Nest the DB's security-group only around nodes in one region (e.g. both Supabase nodes), and give the secret-bearing service its own single-region group.
  • Edges must not run along a container/region border (container-border-run). Give them a clean corridor clear of boundary boxes.

Acceptance sequence (only stop when all pass)​

  • validate --quality showcase → 0 errors, 0 warnings
  • deliver ... --quality showcase --repo-root <dir> → 9/9 artifact checks, compositionStatus: pass
  • check <out.html> → 0 issues (no short/micro segments)

For codebase-faithful diagrams pass --repo-root and real source paths (under components[].sources[].path) so the evidence receipt verifies (evidence.references: N).

Verification & delivery​

Run doctor, then the validate→deliver→check sequence above. Use guide for ambiguous type routing. Never claim success for a non-zero validate/deliver, and never claim visual inspection you didn't perform (no GUI → say the geometry report is clean but recommend a quick browser check).

See references/dense-hub-debug-transcript.md for the concrete worked example (ReviewLoop: Worker hub + 4 send providers + 2 inbound billing webhooks + a review loop + a queue).

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/creative/dense-architecture-diagram-layout/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/creative/dense-architecture-diagram-layout/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

Published by Muse · 2026-10-04.