# Key Files for Understanding Archify's CLI and Schemas

> Understand Archify's CLI and schemas by exploring key files like cli.mjs, validator.mjs, generated-validators.mjs, and schema definitions. Navigate Archify's core logic.

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

---

**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.

```bash

# 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`](https://github.com/tt-a1i/archify/blob/main/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`.

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