Key Source Files for Archify: Complete Guide to the Diagram Rendering Engine

The key source files for Archify are organized into a modular architecture comprising the CLI entry point at archify/bin/archify.mjs, five diagram-specific renderers in archify/renderers/, shared utilities in archify/renderers/shared/, and JSON Schema definitions in archify/schemas/ that validate input before rendering.

Archify is a JavaScript/Node.js-based open-source tool that converts architectural JSON descriptions into visual diagrams including workflows, sequences, lifecycles, data-flows, and architecture grids. Understanding the key source files for Archify is essential for developers looking to extend rendering capabilities, debug diagram generation, or integrate the visualization pipeline into existing applications. The codebase separates concerns across CLI handling, schema validation, geometry calculations, and type-specific rendering modules.

CLI Entry Point and Command Interface

The CLI & Entry Point module serves as the primary interface between users and the rendering engine.

The file archify/bin/archify.mjs implements the archify command-line interface. This module parses command-line arguments, loads JSON diagram definitions from disk, validates them against JSON-Schema specifications, and dispatches the appropriate renderer based on the diagram type specified (workflow, sequence, lifecycle, dataflow, or architecture).

When you execute archify render workflow path/to/file.json, the entry point coordinates the validation and rendering pipeline before outputting the final SVG or HTML file.

Diagram Renderers: Core Visualization Modules

The Renderers directory contains dedicated modules that transform validated JSON models into SVG or HTML output. Each diagram type has its own specialized rendering logic located in archify/renderers/.

Workflow Renderer

The workflow diagram renderer is implemented in archify/renderers/workflow/render-workflow.mjs. The renderWorkflow function exported from this module processes workflow definitions containing steps, decisions, and transitions, calculating layout positions and generating SVG elements that represent process flows.

Sequence Renderer

Sequence diagrams are handled by archify/renderers/sequence/render-sequence.mjs. This file transforms actor and message definitions into timeline-based visualizations showing interaction sequences between system components.

Lifecycle Renderer

The lifecycle diagram renderer in archify/renderers/lifecycle/render-lifecycle.mjs converts state definitions and transition matrices into visual state machines, rendering states as nodes and transitions as labeled edges.

Data-Flow Renderer

Data-flow diagrams are generated by archify/renderers/dataflow/render-dataflow.mjs. This module visualizes data sources, transformations, and sinks as interconnected nodes, handling complex routing and processing logic.

Architecture/Grid Renderer

The architecture renderer located at archify/renderers/architecture/render-architecture.mjs produces grid-based system architecture diagrams, positioning components in hierarchical or layered layouts with connection lines.

Shared Utilities and Validation

The Shared Utilities in archify/renderers/shared/ provide reusable infrastructure for all renderers.

• archify/renderers/shared/validator.mjs: Implements JSON-Schema validation logic through the validate function, ensuring input JSON conforms to expected structures before rendering begins.
• archify/renderers/shared/geometry.mjs: Contains mathematical calculations for node positioning, path routing, and collision detection.
• archify/renderers/shared/utils.mjs: Provides CLI utilities and common helper functions used across rendering modules.
• archify/renderers/shared/layout-report.mjs: Generates diagnostic reports about layout calculations and positioning decisions.

Schema Definitions

The Schemas directory in archify/schemas/ contains JSON-Schema files that strictly define the structure of each diagram definition type.

• archify/schemas/workflow.schema.json: Defines required properties for workflow steps, transitions, and metadata.
• archify/schemas/sequence.schema.json: Specifies the structure for actors, messages, and activation bars in sequence diagrams.

These schemas enable automatic validation through the validator.mjs module and ensure type safety across the rendering pipeline.

Development Scripts and Testing

The Scripts directory contains development-time utilities:

• archify/scripts/generate-validators.mjs: Automatically generates validation code from the JSON Schema files, keeping validators synchronized with schema definitions.
• archify/scripts/render-examples.mjs: Batch processes example diagrams for documentation and regression testing.

The Tests directory in archify/test/ provides comprehensive coverage:

• archify/test/cli.test.mjs: Validates command-line argument parsing and error handling.
• archify/test/render-output-checks.test.mjs: Verifies SVG output structure and diagram correctness.
• archify/test/geometry.test.mjs: Unit tests for geometric calculations and layout algorithms.

Usage Examples

Command-Line Interface

Install Archify globally and render diagrams directly from the terminal:

# Install globally

npm install -g archify

# Render a workflow definition to SVG

archify render workflow path/to/my-workflow.json --output diagram.svg

# Generate a data-flow diagram

archify render dataflow path/to/dataflow.json --output dataflow.svg

Programmatic Integration

Import specific renderers and validators for use in Node.js applications:

import { renderWorkflow } from "archify/renderers/workflow/render-workflow.mjs";
import { validate } from "archify/renderers/shared/validator.mjs";
import workflowDef from "./my-workflow.json" assert { type: "json" };

if (validate(workflowDef, "workflow")) {
  const svg = await renderWorkflow(workflowDef);
  // Write SVG to file or embed in HTML response
}

Summary

The key source files for Archify follow a clear separation of concerns:

• Entry Point: archify/bin/archify.mjs handles CLI operations and orchestrates the rendering pipeline.
• Renderers: Five specialized modules in archify/renderers/ convert validated JSON to SVG for specific diagram types.
• Utilities: Shared helpers in archify/renderers/shared/ manage geometry, validation, and layout reporting.
• Schemas: JSON-Schema definitions in archify/schemas/ enforce input structure and type safety.
• Tooling: Development scripts and comprehensive test suites ensure code quality and schema synchronization.

Frequently Asked Questions

What is the main entry point file for Archify?

The main entry point is archify/bin/archify.mjs, which implements the command-line interface. This file parses arguments, loads JSON definitions, triggers validation against schemas, and dispatches the appropriate renderer module based on the specified diagram type.

How does Archify validate JSON input before rendering?

Validation occurs through archify/renderers/shared/validator.mjs, which checks input against JSON-Schema definitions stored in archify/schemas/. The validate function ensures required fields exist and data types match expectations before handing the model to rendering functions.

Can I use Archify programmatically without the command-line interface?

Yes, you can import individual renderers directly from their module paths. Import renderWorkflow from archify/renderers/workflow/render-workflow.mjs or other specific renderers, then pass validated JSON objects to generate SVG strings programmatically without invoking the CLI.

Where are the diagram rendering tests located in the Archify repository?

Test files are located in the archify/test/ directory. Key files include cli.test.mjs for command-line testing, render-output-checks.test.mjs for verifying SVG generation, and geometry.test.mjs for layout algorithm validation, all using the Mocha testing framework.

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