Key Files for Understanding Archify's CLI and Schemas

The essential files for understanding Archify's CLI and schemas include archify/renderers/shared/cli.mjs for command-line orchestration, archify/renderers/shared/validator.mjs for validation logic, and the auto-generated archify/renderers/shared/generated-validators.mjs module, alongside JSON-Schema definitions in the schemas/ directory.

To comprehend how the tt-a1i/archify repository transforms JSON diagram definitions into standalone HTML visualizations, you must examine the interaction between CLI utilities and the strict schema validation layer. These key files for understanding Archify's CLI and schemas reveal a modular architecture that separates input handling, AJV-based validation, and type-specific rendering. The source code demonstrates how each diagram passes through generated validators before SVG generation occurs.

CLI Entry Point and Shared Utilities

The primary command-line interface resides in archify/renderers/shared/cli.mjs, which exports the loadDiagram and writeDiagram functions that standardize renderer operations. The loadDiagram function parses input files, invokes validateSchema to ensure data integrity against compiled validators, and prepares HTML templates. After rendering completes, writeDiagram populates the template with SVG content, card lists, and metadata, writing the final file to the specified output path.

Helper functions within this module handle accessibility and animation concerns. svgRootAttrs injects ARIA attributes into the SVG root element for screen reader compatibility, while animateAttr manages animation data attributes. These utilities ensure consistent, accessible output across all diagram types in the Archify ecosystem.

# Generate a workflow diagram from the example JSON

node archify/renderers/workflow.mjs examples/workflow.json out.html

Schema Validation Pipeline

Validation relies on a two-layer architecture separating selection logic from compiled AJV validators. The file archify/renderers/shared/validator.mjs acts as a wrapper that chooses the correct validator from archify/renderers/shared/generated-validators.mjs based on the diagram's diagram_type property, formatting detailed error messages when validation fails.

The compiled validators in generated-validators.mjs are produced by scripts/generate-validators.mjs, which processes JSON-Schema definitions from the schemas/ directory (e.g., schemas/workflow.schema.json). This build-time compilation ensures high-performance runtime validation while maintaining the raw JSON schemas as the single source of truth for diagram structure.

Type-Specific Renderers

Individual diagram implementations like archify/renderers/workflow.mjs import shared utilities to handle CLI operations without duplicating boilerplate. These modules call loadDiagram with type-specific configuration, receive validated diagram data, and generate SVG strings and card representations before invoking writeDiagram.

// Inside cli.mjs – loadDiagram
const { diagram, template, outPath } = loadDiagram({
  rendererDir: __dirname,
  diagramType: 'workflow',
  defaultExample: 'workflow.json',
  argv: process.argv,
});
// Later, after rendering...
writeDiagram({
  outPath,
  template,
  meta: diagram.meta,
  footerLabel: 'Workflow',
  svg,               // rendered SVG string
  cards: renderedCards,
});

Each renderer follows this standardized flow: resolve paths, validate against schemas, generate visuals, and output HTML. This design allows new diagram types to leverage existing CLI infrastructure while enforcing strict data validation.

Summary

• archify/renderers/shared/cli.mjs provides the core CLI orchestration with loadDiagram, writeDiagram, and accessibility helpers.
• archify/renderers/shared/validator.mjs selects the appropriate generated validator based on diagram type and formats errors.
• archify/renderers/shared/generated-validators.mjs contains AJV-compiled validation logic for runtime schema enforcement.
• schemas/*.schema.json files define structural requirements for each supported diagram type.
• scripts/generate-validators.mjs compiles JSON schemas into optimized JavaScript validators at build time.
• Type-specific renderers in archify/renderers/<type>.mjs integrate these utilities to process individual formats like workflows.

Frequently Asked Questions

What are the key files for understanding Archify's CLI and schemas?

The key files are archify/renderers/shared/cli.mjs for CLI operations, archify/renderers/shared/validator.mjs and archify/renderers/shared/generated-validators.mjs for validation, type-specific renderers like archify/renderers/workflow.mjs, and the schema definitions in schemas/. These files collectively demonstrate how the tt-a1i/archify repository handles diagram loading, strict JSON-Schema validation, and HTML output generation.

How does Archify validate diagram JSON against schemas?

Archify validates diagrams using a two-stage process where archify/renderers/shared/validator.mjs selects the appropriate compiled validator from archify/renderers/shared/generated-validators.mjs based on the diagram_type field. The generated validators are AJV-compiled functions produced from JSON-Schema files in the schemas/ directory, ensuring strict structural validation before rendering occurs.

Where is the main CLI logic located in Archify?

The main CLI logic resides in archify/renderers/shared/cli.mjs according to the tt-a1i/archify source code. This module exports reusable functions including loadDiagram and writeDiagram that handle file parsing, schema validation invocation, template preparation, and final HTML output generation for all diagram types.

How are the validator functions generated in Archify?

Validator functions are generated by scripts/generate-validators.mjs, which compiles JSON-Schema definitions from the schemas/ directory into optimized AJV validators. The script outputs these compiled functions to archify/renderers/shared/generated-validators.mjs, enabling fast runtime validation while keeping the raw JSON schemas maintainable as the authoritative source for diagram structure.

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