Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
Visual Evolution Round 43 — Clean Flow Gate
Date: 2026-07-20 Status: implementation-ready research decision
Executive decision
Build a shared Clean Flow Gate that rejects one mechanically unambiguous defect across all five typed renderers: a rendered relationship passing through an unrelated semantic node box.
The first slice should not promise that every edge crossing is bad. It should not treat containers, lanes, stages, lifecycle bands, sequence segments, lifelines, or activation bars as ordinary node obstacles. It should also not copy Fireworks' complete showcase budget into Archify. Instead, it should move the existing workflow-only guard into one shared geometry contract and apply that contract to architecture, workflow, dataflow, lifecycle, and sequence before output is written.
resolved relationship + exact authored route points + semantic node boxes
-> split route into line segments
-> ignore source and target boxes
-> test every segment against every unrelated node box with 2px clearance
-> zero hits: render normally, byte-identical geometry
-> hit: fail with a stable, actionable geometry receipt
This is deliberately a correctness gate, not an auto-router. Archify keeps the author's topology and route controls; it refuses to silently publish a route that erases an unrelated node.
Current-worktree audit
The five renderers do not yet share the same relationship guarantee
| Renderer | Existing node/layout checks | Relationship-vs-node check | Important legitimate geometry |
|---|---|---|---|
| Architecture | component bounds, 8px component separation, boundary membership/bounds, short connections, label-vs-component | Missing | a connection from a wrapped component to the outside must cross its boundary |
| Workflow | lane/column bounds, per-lane 8px node separation, phases/groups, short edges, label-vs-node and label-vs-label | Present, using segmentIntersectsRect(..., 2) and excluding endpoints |
edges cross lane, phase, and group frames by design |
| Dataflow | stage/row bounds, 10px node separation, short labeled flows, label-vs-node and label-vs-label | Missing | flows cross stage containers by design |
| Lifecycle | band/column bounds, cross-lane 10px state separation, short transitions, label-vs-state and label-vs-label | Missing | transitions cross lifecycle bands by design |
| Sequence | participant width, timeline bounds, message spacing where x-spans overlap, label-vs-label, segment/activation ranges | No generic routed-edge check | a message from A to C crosses B's lifeline; messages attach to lifelines/activation bars intentionally |
The relevant implementation evidence is in:
archify/renderers/shared/geometry.mjs:segmentIntersectsRectalready provides the shared segment/rectangle primitive;archify/renderers/workflow/render-workflow.mjs: the only renderer that currently expands unrelated node boxes by 2px and rejects a crossing;archify/renderers/architecture/render-architecture.mjs,dataflow/render-dataflow.mjs, andlifecycle/render-lifecycle.mjs: all compute exact route points before validation, but only enforce distance and label collisions; andarchify/scripts/check-render-output.mjs: performs a separate, post-render segment/box calculation only for legend clearance. It does not check relationship paths against semantic nodes.
The CLI's validation path already invokes the renderer before running the
post-render checks. Therefore the Clean Flow Gate belongs beside the exact
route construction, before writeDiagram(), rather than in a second SVG parser
that must reconstruct author intent from markup.
The existing test suite proves the asymmetry
archify/test/layout-rules.test.mjs has a focused negative fixture for a
workflow edge crossing a non-endpoint node, and
archify/test/geometry.test.mjs directly tests the segment/rectangle
primitive. There is no equivalent negative fixture for architecture,
dataflow, or lifecycle, and no sequence-specific exemption fixture.
The repository has 11 canonical examples covering all five renderer types. They are the right compatibility corpus: the new gate must accept all of them unchanged and must not alter the generated SVG/HTML bytes for accepted input.
Primary-source comparison
Fireworks Tech Graph: strict profiles are useful, but profiles matter
Fireworks' official composition contract separates style from geometry and
sets a strict showcase profile: zero edge crossings, zero bridge jumps, at
most two bends per edge, route-stretch and spacing limits, and measurable
clearance around unrelated geometry. It also says container-crossing routes
should use an open corridor rather than run on the container border, and it
keeps stress fixtures separate from showcase baselines.
Source: Fireworks composition-quality contract
Borrow: successful rendering is not sufficient evidence of a clean composition; geometry needs a delivery gate. Adapt: begin with the one invariant Archify can infer exactly from its current schemas: no relationship through an unrelated semantic node. Skip for this slice: Fireworks' zero edge-crossing, bend, stretch, 40px spacing, container-gutter, and bridge budgets. Those belong to a future named quality profile, not an unconditional retrofit over Archify's existing engineering examples.
Graphviz: route around nodes, but do not generalize across routing modes
Graphviz documents that spline routing goes around nodes, while line and
polyline modes are distinct choices. Its orthogonal mode is explicitly limited:
it does not handle ports or, in dot, edge labels. Graphviz also distinguishes
node avoidance from cluster avoidance; only a specific compound-routing mode
is described as avoiding clusters as well as nodes.
Source: Graphviz splines attribute
Borrow: semantic nodes and grouping containers are different obstacle classes. Adapt: Archify should hard-gate peer node boxes and explicitly exempt container frames until it has container ports/corridors. Skip: assuming that choosing an orthogonal path automatically makes ports, labels, and clusters correct.
ELK: crossings are minimized; edge-node spacing is a first-class invariant
ELK Layered supports straight, orthogonal, and spline routing, honors arbitrary
port constraints for orthogonal routes, supports compound graphs, and reorders
layers to minimize edge crossings. Its official Edge Node Spacing option is
specifically the spacing preserved between nodes and edges, with a default of
10. The wording is important: ELK minimizes crossings rather than declaring
that every possible graph can have zero crossings.
Sources:
Borrow: edge-node clearance should be one explicit, reusable contract; source/target ports and compound containers require their own semantics. Adapt: retain Archify's current 2px workflow clearance in the first shared gate so the rollout fixes inconsistency without silently tightening every existing layout. Skip: claiming a global zero-crossing guarantee when Archify is not running a crossing-minimizing layout algorithm.
D2: specialized layout semantics and containers limit universal rules
D2 describes its ELK integration as producing clean orthogonal routes, minimizing crossings, and natively handling container-to-container routing. It also treats sequence diagrams as a specialized ordered layout: messages are ordered, participants have lifelines, groups are sequence containers, and activation spans are explicit semantics.
Sources:
Borrow: renderer-specific semantics must survive a shared quality layer. Adapt: sequence participant header boxes can join the shared semantic-node obstacle set, but lifelines, activations, and segment frames must remain exempt. A valid A-to-C message crossing B's lifeline is not an edge-through-node failure. Skip: treating every visible rectangle or line as the same obstacle type.
Structurizr: manual correction is a legitimate completion path
Structurizr recommends manual layout for precise, consistent positioning. Its editor lets a user add/move relationship vertices, move a relationship label, and switch direct/orthogonal/curved routing. Its automatic-layout documentation also tells users to return to manual mode when auto-layout does not produce a good result.
Sources:
Borrow: a failed route needs a repair path, not a generic “invalid layout”
message.
Adapt: Archify's receipt should point directly to via, route,
fromSide, toSide, or the renderer's placement controls.
Skip: automatic mutation of authored JSON during validation.
Why zero edge-edge crossings is not the Round 43 hard gate
Fireworks' showcase profile proves that zero crossings can be a valuable delivery target. It does not prove that zero is a universal correctness rule. Graphviz and ELK describe crossing reduction/avoidance in the context of specific routing algorithms, D2 exposes different engines and special sequence semantics, and Structurizr offers manual vertices/routing when automatic layout needs correction.
Archify currently has no schema concept for a junction, shared corridor, bridge, or intentional crossing. A geometric intersection alone therefore cannot distinguish:
- an accidental X crossing;
- two relationships sharing a source/target port;
- a T-junction-like branch or merge drawn through common route points;
- two edges intentionally sharing part of a channel; or
- a sequence message crossing an unrelated lifeline.
An unconditional edge-edge gate would either reject legitimate authored
geometry or require undocumented heuristics. Round 43 should record edge-edge
crossing analysis as a later showcase profile candidate, after explicit
junction/port semantics exist. Automatic bridge jumps should remain rejected
as a substitute: they decorate ambiguity rather than remove it.
Bounded Clean Flow Gate contract
Product sentence
Archify never publishes a relationship through an unrelated semantic node, and when it refuses a route it tells the author exactly which segment and which knob to change.
Hard invariant
For each resolved relationship in each typed renderer:
- Use the exact route points already used to render the relationship.
- Split adjacent points into indexed line segments.
- Build an obstacle list containing only the renderer's primary semantic
entity boxes:
- architecture: components;
- workflow: nodes;
- dataflow: nodes;
- lifecycle: states; and
- sequence: participant header boxes.
- Exclude every obstacle whose
idequals the relationship'sfromorto. This is the endpoint-port exemption and also makes a future self-loop deterministic. - Expand every unrelated obstacle by 2px, matching the current workflow behavior, and test every route segment against it.
- Report at most one issue per relationship/obstacle pair, using the first intersecting segment for deterministic output.
- Any hit fails layout validation before the output file is written.
- Accepted diagrams render through the existing code path without changing route points, SVG markup, styles, animation, viewer state, or export.
Explicit exemptions
The gate must not treat the following as semantic node obstacles:
- the relationship's source and target entity boxes;
- architecture boundaries, workflow lanes/phases/groups, dataflow stages, lifecycle bands/lanes, or sequence segment frames;
- sequence lifelines and activation bars;
- background grid, title, footer, legend, story/viewer chrome, or decorative animation layers; and
- edge labels, because existing renderer-specific label collision rules remain the owner of label geometry in this slice.
Container boundaries are not “ignored because they do not matter.” They are exempt because crossing them can be semantically necessary and Archify has no open-gap/container-port model yet. Existing boundary-bounds and legend clearance checks remain intact.
Shared API shape
The implementation should add one pure shared helper rather than copy the workflow loop into four files. A suitable responsibility boundary is:
findRelationshipObstacleHits({
relationships, // [{ index, item, points }]
obstacles, // measured semantic entity rects with id
clearance: 2
})
// -> [{ relationshipIndex, relationship, obstacle,
// segmentIndex, segment, clearance }]
The helper should own segment enumeration, endpoint exclusion, intersection,
deduplication, and deterministic ordering. Renderers should own nouns and repair
advice (Connection/Edge/Flow/Transition/Message, component/node/state,
and their supported routing/placement knobs).
Do not make the shared helper parse SVG, read schema-specific collections, or throw renderer-branded errors. This keeps the geometry oracle pure and directly testable.
Diagnostic contract
Every failure should carry enough evidence for a human or coding agent to fix the JSON without opening the generated artifact. Internally, retain these fields even if the first CLI surface is formatted text:
| Field | Example | Purpose |
|---|---|---|
code |
clean-flow/edge-through-node |
stable machine classification |
diagramType |
dataflow |
renderer context |
relationshipPath |
/flows/3 |
exact JSON collection/index |
relationshipId |
ingest-to-warehouse or null |
stable authored identity when available |
from, to, label |
ingest, warehouse, events |
semantic relationship receipt |
obstacleKind, obstacleId |
node, transform |
unrelated object being crossed |
segmentIndex |
1 |
exact pair in the route points |
segment |
[[260, 180], [500, 180]] |
visible geometry evidence |
clearance |
2 |
threshold that caused rejection |
routing |
route, fromSide, toSide, via values |
current authored controls |
suggestions |
ordered repair options | actionable next moves |
Representative human text:
[clean-flow/edge-through-node] Data-flow /flows/3 "ingest" -> "warehouse"
crosses unrelated node "transform" at segment 1 [260, 180] -> [500, 180]
(2px clearance). Suggested fix: add/adjust via, choose another route/channel,
change fromSide/toSide, or move "transform" to another stage/row.
Renderer-specific final placement hints should be:
- architecture: change
via,route,fromSide/toSide, or componentpos/grid row/column; - workflow: change
via,route/channel,fromSide/toSide, or node lane/column/yOffset; - dataflow: change
via, channel route/coordinates,fromSide/toSide, or node stage/row/yOffset; - lifecycle: change
via, channel route/coordinates,fromSide/toSide, or state column/yOffset; and - sequence: change participant order or message
yif a future layout makes a message hit an unrelated participant header. Never suggest moving a lifeline.
Test contract
Shared geometry unit tests
Add direct tests for:
- one segment crossing an unrelated rectangle;
- a route clearly outside the rectangle;
- a tangent/near route caught by the 2px clearance;
- source and target boxes excluded even though their anchor segment touches their boundary;
- a multi-segment route reporting the first intersecting segment index;
- one issue per relationship/obstacle despite multiple intersecting segments;
- deterministic ordering by relationship index, obstacle order, and segment index; and
- zero-length adjacent points handled deterministically without a crash.
Renderer fixtures
Add focused fixtures whose only new defect is the crossing:
- architecture: straight A -> C through unrelated component B;
- workflow: retain the existing straight left -> right through middle case but assert the new stable receipt fields/message;
- dataflow: stage 0 -> stage 2 through a node in stage 1 on the same row;
- lifecycle: left -> right transition through a middle state in the same band;
- sequence: a positive exemption case where A -> C crosses B's lifeline and remains valid, plus a normal participant-header obstacle test at the shared helper level.
For every negative renderer fixture, assert non-zero exit, stable code,
collection/index or identity, obstacle id, segment index/coordinates, 2px
clearance, and at least one valid repair knob. Also assert the process does not
fall through to a TypeError or write an apparently successful output.
Compatibility and regression gates
- All 11 canonical JSON examples validate and render.
- Existing golden/canonical output remains byte-identical for accepted input.
- Existing label, legend, overlap, finite-coordinate, schema, degraded-mode, route, animation, print, and export tests remain green.
archify validate <type> <input>and direct renderer invocation reject the same bad geometry.- No new schema property or dependency is required.
Browser acceptance
The gate itself is generation-time, so browser QA proves that successful input was not over-tightened or visually mutated; the failure receipt is verified in the terminal.
- Regenerate the 11 canonical examples and open fresh outputs through the in-app browser, not stale file tabs.
- Inspect at least one relationship-dense architecture/workflow artifact at
desktop size and
390 x 844mobile size. - Confirm routes, arrowheads, labels, container crossings, chapter/story controls, trace/focus, zoom, theme, export, and settled animation remain visually unchanged.
- Exercise a valid cross-container route and a sequence A-to-C message that crosses an intermediate lifeline; both must remain visible and valid.
- Confirm zero browser console errors and no page-level horizontal overflow.
- Run one bad fixture in the terminal and confirm it fails before producing a usable artifact with the complete Clean Flow receipt.
Borrow / Adapt / Skip
| Decision | Round 43 contract |
|---|---|
| Borrow | Fireworks' rule that geometry quality is a delivery gate, independent of style. |
| Borrow | Graphviz/ELK's distinction between node avoidance and compound/container routing. |
| Borrow | ELK's explicit edge-node spacing concept. |
| Borrow | Structurizr's actionable manual route controls as the repair path. |
| Adapt | Reuse Archify's exact authored route points and the existing 2px workflow clearance. |
| Adapt | Apply one pure helper across all five renderers while keeping renderer-specific nouns and hints. |
| Adapt | Preserve sequence lifeline/activation semantics and cross-container routes through explicit exemptions. |
| Skip | Automatic rerouting or mutation of authored JSON. |
| Skip | Universal zero edge-edge crossings before junction/shared-corridor semantics exist. |
| Skip | Bridge jumps, decorative duplicate connectors, or copied Fireworks implementation. |
| Skip | New schema fields, quality profiles, dependencies, or post-render SVG reconstruction in this slice. |
Follow-on, only after this gate has real corpus evidence
The next geometry step should be evidence-driven. If the 11 canonical examples
and real user diagrams show repeated edge-edge ambiguity, design an explicit
showcase profile with junction/port/shared-corridor semantics and report
crossing counts, bends, route stretch, and container-border runs. Until then,
the right improvement is the small, strict statement Archify can prove today:
an unrelated node is never used as an edge corridor.