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

> Discover the key source files for Archify's diagram rendering engine. Explore the CLI entry point renderers shared utilities and schema definitions for efficient diagram generation.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-07-20

---

**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`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/workflow.schema.json)**: Defines required properties for workflow steps, transitions, and metadata.
- **[`archify/schemas/sequence.schema.json`](https://github.com/tt-a1i/archify/blob/main/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:

```bash

# 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:

```javascript
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.