Node and Relationship Geometry Controls in Archify: A Complete Technical Guide

Archify treats node and relationship geometry as immutable, canonical data that is captured once during diagram generation and never modified by viewer interactions or presentation controls.

Archify's approach to diagram geometry prioritizes reproducibility and artifact integrity. Unlike interactive diagramming tools that allow real-time manipulation of shapes and connections, Archify enforces a strict separation between authored geometry and viewer presentation. Understanding this architecture is essential for developers integrating Archify into document pipelines or building compliant viewers.

How Node Geometry Works in Archify

Node geometry in Archify is defined at render time and locked for the artifact's lifetime.

Source Definition and Validation

Node shapes—whether <path>, <ellipse>, <rect>, or other SVG elements—are specified in the source JSON and rendered to SVG during diagram generation. The geometry-checking code in examples/web-app.html validates that each node's SVG element is well-formed before display:

// From examples/web-app.html (lines 5047-5055)
// Geometry validation enforces immutability
function validateNodeGeometry(nodeElement) {
    // Confirms path data, dimensions, and anchor points
    // Returns boolean; invalid geometry prevents rendering
}

Once validated, the node's shape, size, and anchor points become part of the canonical artifact. No viewer operation—zoom, pan, theme change, or focus mode—alters these underlying values.

Presentation-Only Modifications

Viewer emphasis such as highlighting, focus rings, or color theme changes apply CSS transforms and overlay elements, not geometric modifications. The original SVG path data remains untouched in the DOM.

Relationship Geometry Controls in Archify

Edge geometry follows the same immutability principles as node geometry.

Captured Path Data

Relationships are rendered as SVG paths or polylines with exact coordinates preserved from the source definition. In examples/web-app.html at line 6047, the edge geometry capture ensures:

// Edge geometry is cloned for animation but never overwritten
const canonicalEdgePath = edgeElement.getAttribute('d');
// Viewer interactions work on copies; original 'd' attribute persists

This implementation guarantees that straight, curved, and polyline edge types maintain their authored form across all view modes and export operations.

Animation and Interaction Handling

When animations or interactive routing previews are needed, Archify clones the edge geometry rather than modifying it. The cloned copy can be transformed or morphed while the canonical path data remains stored on the original element.

Available Viewer Controls and Their Geometry Impact

Archify's viewer interface provides extensive navigation and styling controls, all operating strictly outside the geometry layer:

Control	Key	Geometry Impact
Search	/	None—resets temporary emphasis without altering IR or SVG
Route	R	None—calculates alternative paths without overwriting canonical edges
Lens	L	None—magnification is viewport transform, not node resize
Style	S	None—CSS property changes only
Theme	T	None—color palette swap, no shape modification
Export	E	Preserves original geometry in extracted SVG
Zoom	+	None—viewBox transformation
Reset	0	None—returns to default viewport, original geometry unchanged

The search operation implementation at examples/web-app.html line 11534 demonstrates this separation: temporary node emphasis is achieved through overlay highlighting that resets cleanly without touching the underlying SVG structure.

Geometry Preservation Guarantees

Archify's architecture provides three core guarantees for diagram artifacts:

• Reproducible rendering—identical source produces pixel-identical SVG output
• Immutable geometry—no viewer state persists into the canonical representation
• Clean export—shared or exported diagrams contain only original geometry, never interaction artifacts

These properties make Archify suitable for regulatory documentation, version-controlled diagrams, and auditable visual artifacts where geometric drift would compromise integrity.

Summary

• Node geometry is defined in source JSON, validated at render time, and locked for the artifact lifetime
• Relationship geometry captures exact path data with cloning used for any interactive manipulation
• All viewer controls—search, routing, lens, style, theme, zoom—affect only presentation, never canonical geometry
• Export operations preserve original geometry without accumulated viewer state
• Validation in examples/web-app.html enforces these constraints at lines 5047-5055 (nodes) and 6047 (edges)

Frequently Asked Questions

Can users resize nodes or move connections in the Archify viewer?

No. Archify viewers do not support direct manipulation of node sizes, shapes, or edge paths. These properties are set at diagram generation time and remain immutable. The viewer provides navigation and styling controls that operate through CSS transforms and overlays rather than geometric modification.

How does Archify handle animated transitions between diagram states?

Archify clones canonical geometry for animation purposes. The original path data and node boundaries remain stored on source elements while temporary copies undergo transformation. This applies to routing previews (R key) and any scripted animations, ensuring the canonical representation stays intact.

What happens to geometry when exporting or sharing a diagram?

The Export (E) and Share Card functions extract the current SVG containing only the original, authored geometry. No viewer emphasis, zoom state, or temporary overlays are included in the exported artifact. This produces clean, reproducible diagrams suitable for embedding in documents or version control.

Why doesn't Archify allow interactive geometry editing?

Archify's immutability design serves document integrity use cases. By treating geometry as canonical data, it guarantees that shared diagrams render identically across all viewers and that exported artifacts match the source definition. This trade-off prioritizes auditability and reproducibility over freeform editing capabilities found in tools like Figma or draw.io.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}