How Archify Trace Animation Works in Rendered Diagrams: A Technical Deep Dive

Archify trace animation works by injecting data attributes into SVG elements and driving a CSS keyframe animation that visualizes data flow through nodes and edges.

The tt-a1i/archify repository generates architecture diagrams as standalone SVG files with optional interactive capabilities. When enabled, the archify trace animation creates a visual "pulse" that travels along connections between components, making data flow explicit in rendered diagrams. This feature relies on a combination of metadata-driven SVG attributes, temporary DOM injections, and pure CSS animations rather than JavaScript-based canvas rendering.

How Trace Animation Activates in Archify

The renderer switches to trace mode when specific metadata is present in the diagram's source configuration.

Metadata Configuration

In the JSON source, set the animation field to "trace" and specify a visual preset:

{
  "meta": {
    "animation": "trace",
    "visual_preset": "classic"
  },
  "nodes": [],
  "edges": [
    { "from": "browser", "to": "web-app", "label": "GET /", "trace": true }
  ]
}

CLI Activation

Generate trace-enabled diagrams from the command line using the --animation flag:

node archify/bin/archify.mjs guide "Show a login flow" \
    --animation trace \
    --preset classic \
    --output login-flow.html

The Five-Step Rendering Process

The archify trace animation follows a precise pipeline from source code to visual output.

Step 1: Add Data Attributes to SVG Elements

In archify/assets/template.html, the renderer marks the root <svg> element with data-animation="trace" and applies the preset attribute (e.g., data-preset="classic"). Each edge and node participating in the trace receives specific markers:

• Edges get data-animate="edge"
• Nodes get data-animate="node"

These attributes act as CSS selectors that enable the animation system only when present.

Step 2: Insert Intent-Trace Flow Elements

When a user selects a trace target, JavaScript in experiments/visual-evolution/prototype.mjs creates temporary <g class="intent-trace-flow"> elements. These elements represent the animated pulse moving along the path and receive a data-direction attribute set to "in", "out", or "loop" to control the animation direction.

Step 3: Toggle Active State

The viewer sets data-intent-trace-active="<node-id>" on the root <svg> element once a trace initiates. CSS selectors targeting [data-animation="trace"] only activate when this attribute exists, ensuring animations run on demand rather than on page load.

Step 4: CSS Keyframe Animation

The stylesheet embedded in archify/assets/template.html defines the @keyframes archify-intent-trace-flow animation. Elements with class intent-trace-flow receive:

animation: archify-intent-trace-flow 1.15s linear 1 both;

This keyframe draws a moving highlight—a colored stroke that travels the length of the edge or node shape—creating the visual impression of data traversing the diagram.

Step 5: WebM Video Export

Because the animation lives entirely in SVG and CSS, archify/bin/archify.mjs can export a WebM video of the trace when the browser supports MediaRecorder. This export only functions when animation: "trace" is set in the metadata.

Source Code Implementation Details

The following files implement the archify trace animation system:

• archify/assets/template.html: Contains the CSS keyframes and data attribute selectors that power the visual trace effect
• archify/bin/archify.mjs: CLI entry point that passes animation flags to the renderer and handles WebM export logic
• experiments/visual-evolution/prototype.mjs: Demonstrates runtime injection of trace-flow elements and direction control
• examples/web-app-rendered.html: Production example showing SVG with trace attributes and interactive UI

Practical Code Examples

When rendered, the SVG structure includes animation markers:

<svg viewBox="0 0 720 900" data-animation="trace" data-preset="classic">
  <g data-animate="edge" data-edge-from="browser" data-edge-to="web-app">
    <path d="…"/>
  </g>
  <g data-animate="node" data-node-id="browser"><circle …/></g>
</svg>

Upon user interaction, the viewer injects the animated element:

<g class="intent-trace-flow" data-direction="out">
  <path d="…"/>
</g>

The CSS engine then animates this element via the archify-intent-trace-flow keyframe definition.

Summary

• Archify generates stand-alone SVG files with trace capabilities controlled by JSON metadata
• The data-animation="trace" attribute triggers a CSS-based animation system
• JavaScript creates temporary .intent-trace-flow elements that travel along edges marked with data-animate="edge"
• The archify-intent-trace-flow keyframe animates a 1.15-second pulse along paths
• WebM export is available through archify/bin/archify.mjs when trace mode is enabled

Frequently Asked Questions

What file formats does Archify use for trace animations?

Archify produces diagrams as standalone SVG files with embedded CSS. The trace animation requires no external JavaScript libraries or canvas elements, keeping the output lightweight and portable across browsers.

How do I enable trace animation in Archify diagrams?

Add "animation": "trace" to the meta section of your diagram's JSON source, or use the --animation trace flag when running archify/bin/archify.mjs from the command line.

Can Archify export trace animations as video?

Yes. When animation: "trace" is configured, archify/bin/archify.mjs can export WebM videos of the animation using the browser's MediaRecorder API, but only if the browser supports that API.

What controls the direction of the trace animation?

The data-direction attribute on .intent-trace-flow elements controls direction, as implemented in experiments/visual-evolution/prototype.mjs. Valid values are "in", "out", or "loop", determining whether the pulse travels toward a node, away from it, or cycles continuously.

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