How to Integrate Archify with Other Tools: Complete Guide to Viewer Embedding and CLI Automation

Integrate Archify by either embedding its JavaScript viewer in web applications to manipulate architecture diagrams programmatically, or by installing the DeepSeek Harness (DSH) skill to generate automated architecture exports from the command line.

Archify is a modular, client-side visualization library that exposes a global Archify namespace for rendering interactive architecture diagrams. Whether you need to embed live viewers in internal documentation dashboards or automate architecture mapping in CI pipelines, knowing how to integrate Archify with other tools allows you to extend its core capabilities without modifying the underlying source. This guide covers the two primary integration patterns: web viewer embedding and DeepSeek Harness CLI invocation.

Embedding the Archify Viewer in Web Applications

The Archify viewer is a pure JavaScript/HTML solution that loads via standard script tags. The core architecture exposes functional modules—such as radar, guidedViews, and routeProbe—as properties on the global Archify object, allowing external applications to drive the UI programmatically according to the command dispatcher defined in [viewer/template.source.html](https://github.com/tt-a1i/archify/blob/main/viewer/template.source.html#L5510-L6030).

Loading and Initializing the Viewer

To embed Archify, include the required viewer scripts in your HTML head, then initialize the layout manager. The waitForStableLayout method returns a promise that resolves once the rendering engine is ready.

<!doctype html>
<html>
<head>
  <script src="viewer/viewer-chrome-layout.js"></script>
  <script src="viewer/viewer-camera.js"></script>
  <script src="viewer/viewer-semantic-radar.js"></script>
</head>
<body>
  <div id="archify-root"></div>
  <script>
    // Initialize and open the radar view
    Archify.waitForStableLayout().then(() => {
      Archify.radar.open();
    });
  </script>
</body>
</html>

Controlling the UI Programmatically

Once loaded, the viewer exposes a unified command dispatcher that maps JavaScript API calls to keyboard shortcuts. In [viewer/template.source.html](https://github.com/tt-a1i/archify/blob/main/viewer/template.source.html#L6167-L6206), the core binds methods like Archify.view.zoomIn() and Archify.radar.sync() to specific key combinations. You can trigger these actions directly without user interaction.

For example, to start a guided tour programmatically:

// Open radar, zoom in, then play guided views
Archify.radar.open();
Archify.view.zoomIn();
Archify.guidedViews.play();

The command dispatcher handles the underlying event propagation, ensuring that modules like semanticLens and routeProbe receive synchronized updates.

Command-Line Integration via DeepSeek Harness

For automated workflows, Archify integrates with the DeepSeek Harness (DSH) as a registered skill. This allows AI assistants and CLI tools to invoke Archify in headless mode, generate deterministic ZIP exports, and return structured JSON receipts for downstream processing.

Installing the DSH Skill

The DSH adapter is located in the integrations/deepseek-harness/ directory. Install it using the DSH plugin manager as documented in the main README:

# Install the DSH plugin (opt-in)

dsh plugin --profile web add @tt-a1i/archify-dsh@0.1.0

The adapter requires Node.js version ^22.19.0 or >=24.0.0 as specified in the integration documentation.

Invoking Archify from the CLI

After installation, invoke the skill using natural language commands recognized by DSH-compatible assistants. This executes Archify in a headless Chromium environment, captures the architecture proof, and packages it as archify.zip.

# Invoke the skill via DSH

dsh run "Use the archify skill to map this repository's runtime architecture."

Under the hood, the skill runner executes the same viewer code found in [viewer/viewer-chrome-layout.js](https://github.com/tt-a1i/archify/blob/main/viewer/viewer-chrome-layout.js#L110-L112), but without the browser chrome. The resulting export conforms to the CLI output types validated in archify/test/cli-output-types.test.mjs.

CI/CD and Automated Testing Integration

Archify supports automated testing environments through environment variables and headless execution scripts. This enables integration into build pipelines for continuous architecture documentation.

Running Headless Exports in CI

Set the ARCHIFY_SITE_INTEGRATION environment variable to 1 to activate the full export pipeline during CI runs. The test suite in archify/test/site-language-continuity.test.mjs demonstrates how to validate viewer functionality in automated environments without a display server.

For deterministic exports in CI workflows, spawn the Archify test runner directly:

import { spawn } from 'child_process';

// Generate architecture artifacts in headless mode
spawn('node', ['archify/test/webm-artifact.smoke.mjs'], { stdio: 'inherit' });

This pattern is useful for generating up-to-date architecture diagrams as part of documentation builds or deployment previews.

Extending Archify with Custom Modules

The Archify architecture supports safe module extension through defensive programming patterns. Each module checks for the existence of its counterparts before invocation, allowing you to inject custom functionality without breaking core features.

For instance, the layout manager in [viewer/viewer-chrome-layout.js](https://github.com/tt-a1i/archify/blob/main/viewer/viewer-chrome-layout.js#L110-L112) verifies module availability before syncing:

// Safe module interaction pattern
if (Archify.radar && typeof Archify.radar.sync === 'function') {
  Archify.radar.sync();
}

This allows teams to develop proprietary "metrics" panels or custom "exporters" that coexist with standard viewer components, simply by attaching new methods to the global Archify object before initialization.

Summary

• Embed via JavaScript: Load viewer-chrome-layout.js and related scripts, then call Archify.waitForStableLayout() to initialize the viewer in any web context.
• Automate via DSH: Install @tt-a1i/archify-dsh and invoke natural language commands to generate headless architecture exports for CI pipelines.
• Defensive extension: Add custom modules by checking for existing Archify properties before invocation, ensuring compatibility with future updates.
• CI integration: Use ARCHIFY_SITE_INTEGRATION=1 and the smoke test suite to validate Archify functionality in automated build environments.

Frequently Asked Questions

How do I integrate Archify into a React or Vue application?

Since Archify exposes a global Archify object, you can load the viewer scripts dynamically in React using useEffect or in Vue using mounted hooks. Initialize with Archify.waitForStableLayout() after the container DOM element mounts, then call methods like Archify.radar.open() to control the visualization state from your framework's lifecycle methods.

Can I use Archify without installing the DeepSeek Harness?

Yes. The DSH integration is optional and provides CLI access for AI assistants. For standard tooling integration, use the programmatic JavaScript API or spawn the headless test scripts directly via Node.js, as demonstrated in the webm-artifact.smoke.mjs example, to generate exports without the DSH wrapper.

What Node.js versions are required for CLI integration?

The DeepSeek Harness adapter requires Node.js ^22.19.0 or >=24.0.0 to run the skill properly. This is documented in the [integrations/deepseek-harness/README.md](https://github.com/tt-a1i/archify/blob/main/integrations/deepseek-harness/README.md) file.

How do I automate Archify exports in GitHub Actions?

Set the ARCHIFY_SITE_INTEGRATION=1 environment variable in your workflow file and run the CLI tests using node archify/test/site-language-continuity.test.mjs. This validates the viewer pipeline in headless mode, allowing you to commit generated architecture artifacts back to your repository or upload them as build artifacts.

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