Per-Diagram Rendering Engines in Archify: The Five Core Renderers Explained

Archify assigns a dedicated rendering engine to each diagram type, with five specialized modules in archify/renderers/ that convert typed JSON IR into deterministic HTML/SVG output based on the type field.

The tt-a1i/archify repository implements a modular visualization system where per-diagram rendering engines handle the conversion of structured data into publishable diagrams. Each engine specializes in a specific visual paradigm—ranging from hierarchical architecture charts to temporal sequence flows—ensuring deterministic layout algorithms and consistent HTML/SVG output across all supported diagram categories.

The Five Per-Diagram Rendering Engines

Archify supports five diagram categories, each backed by a distinct renderer module that implements layout logic tailored to that visual domain.

Architecture Renderer

Located at archify/renderers/architectureRenderer.mjs, this engine manages hierarchical component placement for system architecture diagrams. It respects deployment ownership, boundary constraints, and ownership profiles when positioning elements, producing deterministic visualizations of complex system topologies.

Workflow Renderer

The archify/renderers/workflowRenderer.mjs module implements a lane-based flow layout designed to keep the happy path visible across parallel lanes and conditional branches. This engine is optimized for process automation and agent tool-call visualizations, ensuring clear separation of concurrent execution paths.

Sequence Renderer

Found in archify/renderers/sequenceRenderer.mjs, this engine handles temporal ordering of call-and-return pairs. It draws a left-to-right timeline with optional timing markers, making it ideal for cache-miss analysis and API interaction flows where chronological accuracy is critical.

Data Flow Renderer

The archify/renderers/dataFlowRenderer.mjs engine applies a pipe-and-filter style layout that emphasizes data sources, transformation steps, storage systems, and PII-sensitivity boundaries. It visually distinguishes between ingress, processing, and persistence stages while highlighting sensitive data boundaries.

Lifecycle Renderer

Located at archify/renderers/lifecycleRenderer.mjs, this engine renders state-machine style diagrams that visualize retries, wait states, terminal outcomes, and event-driven transitions. It is the default choice for async process evolution and entity state management visualizations.

How the Rendering Engine Selection Works

The dispatch logic resides in archify/bin/archify.mjs, the CLI entry point that parses command-line arguments and inspects the type field of the supplied JSON. The renderDiagram function contains a switch statement that routes to the appropriate module:

switch (type) {
  case 'architecture': return architectureRenderer.render(...);
  case 'workflow':     return workflowRenderer.render(...);
  case 'sequence':     return sequenceRenderer.render(...);
  case 'dataflow':     return dataFlowRenderer.render(...);
  case 'lifecycle':    return lifecycleRenderer.render(...);
}

This design ensures that each diagram type invokes only the renderer capable of interpreting its specific semantic constraints and layout requirements.

JSON IR and Visual Presets

All five rendering engines consume the same typed JSON IR (Intermediate Representation) defined in archify/schemas/. While the structural data remains consistent across diagram types, the visual presentation varies through the meta.visual_preset field.

Available presets include signal-flow, blueprint, and classic, each determining color palettes, animation behavior, and label styling. The renderer applies the preset after validating the JSON IR against the schema, producing final HTML or SVG output that matches the selected aesthetic.

Rendering Examples

To render an Architecture diagram with the signal-flow preset:

const archJson = require('./examples/web-app.architecture.json')
await renderDiagram({
  type: 'architecture',               // ← selects architectureRenderer
  source: archJson,
  visual_preset: 'signal-flow',       // preset influences colours/animation
  output: 'web-app-arch.html'
})

For a Workflow diagram using the blueprint preset:

await renderDiagram({
  type: 'workflow',
  source: require('./examples/agent-tool-call.workflow.json'),
  visual_preset: 'blueprint',
  output: 'agent-workflow.html'
})

To generate a Sequence diagram with the classic preset:

await renderDiagram({
  type: 'sequence',
  source: require('./examples/cache-miss.sequence.json'),
  visual_preset: 'classic',
  output: 'cache-seq.html'
})

Summary

• Five specialized engines: Architecture, Workflow, Sequence, Data Flow, and Lifecycle each have dedicated renderer modules in archify/renderers/.
• Dispatch mechanism: The renderDiagram function in archify/bin/archify.mjs routes requests based on the type field in the JSON input.
• Shared input format: All engines consume the same typed JSON IR from archify/schemas/, ensuring consistent data validation.
• Visual customization: The meta.visual_preset field controls styling without altering the underlying data structure.
• Deterministic output: Each renderer implements layout algorithms specific to its diagram category, producing predictable HTML/SVG results with optional motion.

Frequently Asked Questions

What file contains the dispatch logic for selecting a rendering engine?

The dispatch logic lives in archify/bin/archify.mjs, specifically within the renderDiagram function. This CLI driver inspects the type property of the input JSON and executes a switch statement to invoke the correct renderer module from archify/renderers/.

How does Archify validate diagram input before rendering?

All rendering engines validate input against the typed JSON IR schema located in archify/schemas/. This schema defines the contract between the CLI and the renderers, ensuring that required fields and data types are present before the layout algorithm executes.

Can I customize the visual style of a diagram without changing the data?

Yes. Set the meta.visual_preset field in your source JSON to values like signal-flow, blueprint, or classic. The rendering engine applies this preset to determine colors, animations, and label styles while leaving the structural data in the IR unchanged.

Which rendering engine should I use for microservice deployment diagrams?

Use the Architecture Renderer (archify/renderers/architectureRenderer.mjs). This engine specializes in hierarchical component placement and understands deployment ownership and boundary constraints, making it the appropriate choice for visualizing microservice topologies and infrastructure ownership.

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