# Understanding the Architecture of Archify: A 4-Layer Deterministic Pipeline

> Discover Archify's 4-layer deterministic pipeline. Learn how this rendering pipeline transforms JSON to interactive HTML diagrams through Authoring, Validation, Rendering, and Viewing.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: architecture
- Published: 2026-09-12

---

**Archify is a self-contained, deterministic rendering pipeline that transforms typed JSON intermediate representations into interactive HTML diagrams through four tightly coupled layers: Authoring, Validation, Rendering, and Viewing.**

The architecture of Archify represents a pure-function approach to diagram generation, ensuring that identical inputs always produce identical visual outputs. According to the `tt-a1i/archify` source code, this Node.js-based system operates entirely without server dependencies, compiling structured data into static assets that include embedded SVG and a lightweight client-side runtime.

## The Four Layers of the Archify Architecture

### 1. Authoring and JSON IR

The **Authoring layer** accepts plain-language descriptions or structured input and converts them into a typed JSON Intermediate Representation (IR). This IR serves as the single source of truth for all downstream processing. The schema definitions for each diagram type reside in `archify/schemas/`, enforcing type safety before any rendering begins. Sample JSON candidates demonstrating valid IR structures are available in the `archify/examples/` directory.

### 2. Validation Engine

Before rendering occurs, the **Validation Engine** checks the JSON IR for schema compliance, layout invariants, and semantic correctness. Implemented primarily in `archify/bin/archify.mjs`, this layer returns a machine-readable diagnostic receipt that enumerates any issues and suggests specific fixes. Validation is invoked via the CLI using the `validate` command, ensuring that only well-formed IR proceeds to the rendering stage.

### 3. Deterministic Renderer

Once validation passes, the **Deterministic Renderer** compiles the JSON IR into static assets through a pure-function-style process. Located in `archify/bin/archify.mjs` and the `renderers/` directory (where [`renderers/workflow/README.md`](https://github.com/tt-a1i/archify/blob/main/renderers/workflow/README.md) defines specific layout contracts), this layer generates an HTML file embedding SVG diagrams. The renderer also supports optional exports to PNG, JPEG, WebP, and WEBM formats. Because the rendering logic is deterministic, the same IR always produces byte-identical output, making the artifacts suitable for version control and automated testing.

### 4. Viewer Runtime

The generated HTML bundles a **Viewer Runtime** that requires no server-side processing. Implemented in the `viewer/` directory—specifically in files like [`viewer/viewer-chrome-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer/viewer-chrome-layout.js) and [`viewer/semantic-radar.js`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-radar.js)—this client-side JavaScript provides interactive capabilities including theme switching, pan/zoom, search, focus modes, route tracing, semantic lenses, and guided stories. Users interact with the diagram directly in the browser using keyboard shortcuts such as `/` for search, `R` for route probe, `L` for semantic lens, and `S` for visual preset changes.

## How the Pipeline Executes

The architecture follows a strict linear progression from input to interactive output:

1. **Input** – An agent or user provides a description, which converts into the typed JSON IR.

2. **Validate** – The command `node bin/archify.mjs validate <type> <candidate.json>` ensures schema compliance and emits a diagnostic receipt if the IR violates any constraints.

3. **Render** – The command `node bin/archify.mjs deliver <type> <candidate.json> <output.html>` deterministically produces the final HTML/SVG artifact, freezing both the input data and the visual representation.

4. **View** – The delivered HTML runs the viewer runtime locally, enabling interactive exploration without additional processing or network requests.

## CLI Commands by Architecture Layer

Each layer of the architecture exposes specific CLI functionality in `archify/bin/archify.mjs`:

```bash

# Layer 1: Authoring - Generate a typed JSON IR from plain language

node bin/archify.mjs guide "Browser -> API -> Redis cache -> PostgreSQL fallback" --json > candidate.json

# Layer 2: Validation - Run the Validation Engine with quality checks

node bin/archify.mjs validate architecture candidate.json \
  --quality showcase \
  --json  # Outputs diagnostic receipt

# Layer 3: Rendering - Deterministically generate static assets

node bin/archify.mjs deliver architecture candidate.json \
  output.html \
  --quality showcase \
  --open  # Opens the generated HTML automatically

# Layer 4: Viewing - Interact with the bundled viewer (no command required)

# Open output.html in a browser and use:

#   /  → Search/focus

#   R  → Route probe

#   L  → Semantic lens

#   S  → Change visual preset

```

These commands support multiple diagram types including `architecture`, `workflow`, `sequence`, `dataflow`, and `lifecycle`.

## Key Source Files and Responsibilities

The architecture is implemented across several critical directories in the `tt-a1i/archify` repository:

- **`archify/bin/archify.mjs`** – CLI entry point orchestrating validation, delivery, and preview commands.

- **`archify/schemas/`** – JSON schema definitions that enforce the IR structure for each diagram type.

- **[`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md)** – Formal skill definition outlining the type router, authoring rules, and pipeline specifications.

- **`examples/`** – Ready-made JSON candidates used for testing and demonstration purposes.

- **`renderers/`** – Layout logic and rendering contracts that transform validated IR into SVG.

- **`viewer/`** – Client-side JavaScript powering the interactive HTML viewer, including [`viewer-chrome-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer-chrome-layout.js) and [`semantic-radar.js`](https://github.com/tt-a1i/archify/blob/main/semantic-radar.js).

- **[`README.md`](https://github.com/tt-a1i/archify/blob/main/README.md)** – High-level product overview documenting the "generate → validate → preview → deliver" workflow.

## Summary

- **Archify** implements a four-layer deterministic pipeline: Authoring (JSON IR), Validation, Rendering, and Viewing.

- The **JSON IR** in `archify/schemas/` serves as the immutable contract between layers, ensuring type safety and reproducibility.

- **Validation** occurs via `archify.mjs validate`, producing machine-readable diagnostic receipts before any rendering begins.

- **Rendering** is deterministic and pure-functional, guaranteeing that identical IR inputs produce byte-identical HTML/SVG outputs.

- The **Viewer Runtime** operates entirely client-side in `viewer/`, requiring no server infrastructure while providing rich interactivity through keyboard shortcuts.

## Frequently Asked Questions

### What makes Archify's architecture deterministic?

The rendering pipeline in `archify/bin/archify.mjs` implements pure-function-style compilation where the same JSON IR always produces identical HTML, SVG, and export files. This deterministic behavior ensures visual consistency across different environments and makes outputs safe for version control and automated CI/CD checks.

### How does the Validation Engine work?

The Validation Engine, located in the core library, checks JSON IR against schemas in `archify/schemas/` and layout rules defined for each diagram type. When invoked via `archify.mjs validate`, it returns a structured receipt listing schema violations, layout invariant breaches, or semantic errors with suggested corrections.

### What diagram types does Archify support?

According to [`archify/SKILL.md`](https://github.com/tt-a1i/archify/blob/main/archify/SKILL.md), the architecture supports five diagram types: `architecture`, `workflow`, `sequence`, `dataflow`, and `lifecycle`. Each type maintains its own schema definition and rendering contract in the `renderers/` directory.

### Can I use Archify without a server?

Yes. The architecture is entirely self-contained—the Deterministic Renderer produces static HTML files that bundle the Viewer Runtime. Once generated, these files run entirely in the browser without requiring Node.js, external APIs, or hosting infrastructure, as all interactivity is implemented in pure JavaScript under `viewer/`.