Archify Diagram Creation and Management: Features and Capabilities

Archify is a zero-dependency, single-file architecture visualization tool that enables complete diagram creation and management through declarative JSON recipes, specialized renderers, and interactive HTML viewers with guided storytelling capabilities.

Archify, developed in the tt-a1i/archify repository, provides a lightweight yet comprehensive solution for diagram creation and management. Unlike traditional visualization tools that require heavy runtime dependencies, Archify generates portable, interactive HTML diagrams directly from JSON configuration files, making it ideal for documentation sites and CI pipelines.

Declarative Recipe-Based Authoring

At the core of Archify's diagram creation workflow is the JSON recipe system. These plain-JSON files serve as the single source of truth for your diagrams, describing nodes, edges, layout hints, and story steps in a human-readable format.

Recipes reside in the archify/recipes/ directory and define every aspect of your visualization without requiring code changes. When you run the render command, Archify injects this recipe data into archify/assets/template.html, which provides the UI scaffolding including the toolbar, minimap, and story panel. This separation of data from presentation allows you to evolve visual styles across all diagrams by modifying the template without touching individual recipe files.

Dual Rendering Architecture

Archify supports multiple diagram types through specialized renderers that share common layout utilities but apply domain-specific visualization logic.

Architecture Renderer

The architecture renderer (archify/renderers/architecture/render-architecture.mjs) handles static system architecture diagrams. It processes node hierarchies, connection lines, and grouping structures to produce clean, navigable views of complex systems. This renderer optimizes for clarity in component relationships and layered system boundaries.

Workflow Renderer

The workflow renderer (archify/renderers/workflow/render-workflow.mjs) specializes in execution-flow diagrams. It visualizes process steps, decision points, and transitions with animations that indicate flow direction. Unlike the static architecture view, this renderer emphasizes temporal sequences and state changes, making it suitable for documenting business processes or algorithm execution.

Interactive Viewer Features

The generated HTML viewer in archify/assets/template.html provides sophisticated interaction capabilities without requiring a backend server.

Semantic Zoom and Radar View

Archify implements semantic zoom with three distinct thresholds: READ, FULL, and MAP. As users zoom in from overview to detail (controlled by logic in archify/assets/template.html lines 73-78), the viewer automatically switches rendering modes—showing minimal labels at MAP level, full details at READ level, and intermediate information at FULL level. This preserves performance while ensuring users always see relevant information at their current zoom level.

Relationship Lens

The relationship lens feature (implemented in archify/assets/template.html lines 118-127) activates on hover or click, highlighting inbound and outbound connections for any selected node. The lens uses "pulse" animations to draw attention to related elements, making it easy to trace dependencies in dense diagrams without losing context of the overall structure.

Guided Story Engine

Authors can embed linear or branching stories within recipes that guide readers through complex diagrams step-by-step. The story engine (found in archify/assets/template.html lines 3642-3679) supports scene changes, focus movements, and animation cues that run in-page. This transforms static documentation into interactive tutorials, letting you walk stakeholders through architecture decisions or onboarding paths with precise visual cues.

Navigation and Discovery

Finding specific components in large diagrams is streamlined through the node finder system tested in archify/test/finder.test.mjs. This searchable index allows users to locate any node by label, type, or tag, then instantly jump to that element's position in the canvas. The finder integrates with the semantic zoom system to ensure the target node is visible at the appropriate detail level when selected.

Validation and CI Integration

Archify treats diagram quality as a first-class concern, providing automated validation tools that integrate into continuous integration pipelines.

Geometry Validation

The archify validate command runs a comprehensive suite of geometry checks defined in archify/renderers/shared/layout-report.mjs. These checks detect node overlaps, improper edge crossings, and out-of-bounds elements that could compromise readability. When invoked with the --json flag, the validator returns a machine-readable report suitable for CI gating:

archify validate architecture examples/archify-repo.json --json > validation-report.json

This command fails with a non-zero exit code if geometry violations exist, preventing broken diagrams from reaching production documentation.

Automated Testing Suite

The repository includes a full test harness in archify/test/ covering rendering compatibility, navigation stability, and zoom behavior. Files like archify/test/semantic-zoom.test.mjs ensure that threshold transitions remain consistent across renderer updates, while archify/test/finder.test.mjs validates search functionality. These tests guarantee that recipe changes or renderer updates do not break existing diagrams.

Command Line Interface

Archify exposes its functionality through the archify binary defined in archify/package.json, supporting four primary sub-commands for scripting and automation.

Rendering and Export

Generate interactive HTML pages or static assets using the render command:

# Create an interactive HTML diagram

archify render architecture examples/archify-repo.json > docs/archify-repo.html

# Export a static SVG for presentations

archify render architecture examples/archify-repo.json --export svg > archify-repo.svg

Guided Tours

Execute story definitions to verify narrative flows or generate guided documentation:

archify guide examples/archify-repo.json --story

Inspection and Debugging

The inspect sub-command provides detailed metadata about recipe structures without rendering, useful for debugging complex hierarchies or automated documentation generators.

Summary

• Zero-dependency deployment: Single HTML file output requires no server-side runtime or external libraries.
• Declarative JSON recipes: Plain-text configuration files in archify/recipes/ serve as the single source of truth for diagram structure and content.
• Dual renderer support: Specialized engines in archify/renderers/ handle both static architecture diagrams and dynamic workflow visualizations.
• Semantic zoom levels: Automatic switching between READ, FULL, and MAP detail thresholds maintains usability across zoom ranges.
• Integrated validation: The archify validate command with layout-report.mjs prevents geometry errors in CI pipelines.
• Interactive storytelling: Built-in story engine enables step-by-step guided tours without code modifications.
• Portable CLI workflow: Commands for rendering, guiding, validating, and exporting support automated documentation pipelines.

Frequently Asked Questions

What file format does Archify use for diagram definitions?

Archify uses plain JSON recipe files stored in the archify/recipes/ directory. These files declaratively describe nodes, edges, layout hints, and story steps without requiring JavaScript or markup knowledge. The JSON structure serves as the single source of truth, which renderers in archify/renderers/ transform into interactive visualizations.

How does Archify handle large diagrams with many elements?

Archify implements semantic zoom with three distinct thresholds (READ, FULL, and MAP) controlled by logic in archify/assets/template.html. As users zoom out to MAP level, labels simplify and detail reduces to maintain performance. The node finder functionality (tested in archify/test/finder.test.mjs) allows instant search and navigation to specific elements regardless of current zoom level, while the relationship lens helps isolate relevant connections without overwhelming the viewer with full graph complexity.

Can Archify diagrams be used in CI/CD pipelines for documentation validation?

Yes. The archify validate command runs geometry checks via archify/renderers/shared/layout-report.mjs to detect node overlaps, edge crossings, and boundary violations. When combined with the --json flag, it outputs machine-readable reports suitable for CI gating. The repository's test suite in archify/test/ (including semantic-zoom.test.mjs) ensures renderer stability, allowing teams to verify diagram integrity automatically before merging documentation changes.

Is it possible to export Archify diagrams to static image formats?

Yes. The archify render command supports --export svg and PNG output modes in addition to the default interactive HTML generation. This enables use of Archify diagrams in slide decks, PDF documentation, or printed materials while maintaining the ability to generate interactive versions for web deployment from the same JSON recipe source.

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