# How to Interpret Archify Analysis Results: A Complete Guide to Reading Architecture JSON Output

> Master Archify analysis results with this guide. Learn to interpret architecture JSON output by mapping fields to visual diagram elements. Understand your system's structure.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: how-to-guide
- Published: 2026-08-11

---

**Archify analysis results are strict JSON documents that describe system architecture through typed components, connections, and boundaries, which you interpret by mapping each schema-defined field to its visual counterpart in the rendered HTML diagram.**

Archify transforms codebases and system descriptions into **typed JSON representations** called *analysis results*. These results follow a strict schema defined in [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json), making every field purposeful and verifiable. Understanding how to read this structure lets you trace design decisions back to source code and validate architectural claims.

This guide walks through each section of an Archify result, shows how to validate and render it, and demonstrates interpretation with real examples from the `tt-a1i/archify` repository.

---

## The Core Sections of an Archify Analysis Result

Every analysis result contains six primary sections. Master these and you can interpret any Archify output.

### Meta: Document Metadata and Rendering Directives

The `meta` object defines the diagram's identity and visual behavior.

| Field | Purpose | Example Value |
|-------|---------|---------------|
| `title` | System or diagram name | "Archify" |
| `subtitle` | Brief description | "Architecture analysis pipeline" |
| `visual_preset` | Color/style theme | `signal-flow`, `blueprint` |
| `animation` | Edge animation on hover | `"trace"` or `"none"` |
| `output` | Destination path for HTML artifact | [`./archify-repo.html`](https://github.com/tt-a1i/archify/blob/main/./archify-repo.html) |

The `visual_preset` selects predefined palettes for different audiences—engineers often prefer `signal-flow` for data-flow clarity, while `blueprint` suits formal documentation.

### Layout: Deterministic Positioning (Optional)

When present, `layout` reveals that Archify used **grid-mode placement** rather than auto-layout. The fields `origin`, `cols`, `gapX`, `gapY`, `cellW`, and `cellH` let you reproduce exact positions in custom renderers or verify spacing consistency.

### Components: The Nodes of Your Architecture

The `components` array contains every architectural element. Each component object includes:

- **`id`** – Unique identifier referenced by connections
- **`type`** – Determines node color (frontend, backend, external, security, database, etc.)
- **`label`** – Primary display name
- **`sublabel`** – Secondary description (optional)
- **`pos`** – `[x, y]` screen coordinates
- **`size`** – `[width, height]` dimensions
- **`sources`** – Traceable evidence array with `file`, `line_start`, `line_end`

The `sources` array is critical for **grounded architecture**—it lets you verify that a component claim maps to actual code. For example, a database component might source to `src/models/user.ts:15-42`.

### Boundaries: Grouping and Trust Regions

`boundaries` define visual containers that wrap component IDs via a `wraps` array. Each boundary has a `kind`: `region` for logical groups or `security-group` for trust boundaries. Use these to answer scope questions like *"Which components belong to the payment processing zone?"*

### Connections: Data Flow and Relationships

The `connections` array defines **directed edges** with these key fields:

- **`from`** / **`to`** – Component IDs defining directionality
- **`variant`** – Visual emphasis: `"emphasis"` (critical path), `"security"` (trust crossing), `"dashed"` (optional/conditional)
- **`fromSide`** / **`toSide`** – Which edge of the source/target node connects (`"top"`, `"bottom"`, `"left"`, `"right"`)
- **`route`** – Path style: `"straight"`, `"orthogonal"`
- **`via`** – Array of waypoint coordinates for custom routing

Trace data flow by following `from` → `to` chains, respecting `variant` to identify critical vs. optional paths.

### Cards: Explanatory Narratives

`cards` attach free-form documentation to the diagram. Each card has a `title`, `color` (as dot indicator), and `content` (markdown string). These surface design decisions, quality-gate explanations, or agent-generated narratives that aren't captured in formal structure.

### Meta.Views: Deep-Linkable Perspectives

The optional `meta.views` array contains **guided view definitions** with parameters like `focus`, `lens`, and `route`. These encode URL fragments such as `#focus=id&reach=upstream`, letting you share specific perspectives without manual navigation.

---

## How to Validate and Render Archify Results

The `archify/bin/archify.mjs` CLI provides `validate` and `deliver` commands for working with analysis results.

### Validating a Result

```javascript
import { validate } from 'archify/bin/archify.mjs';
import fs from 'fs';

const result = JSON.parse(
  fs.readFileSync('examples/archify-repo.architecture.json', 'utf-8')
);

// Validate against architecture.schema.json
const report = await validate('architecture', result, { json: true });
console.log('Validation report:', report);

```

A successful validation returns `{ diagnostics: [] }`. Failures produce **machine-readable error receipts** pointing to exact schema violations with JSONPath locations.

Terminal equivalent:

```bash
node archify/bin/archify.mjs validate architecture examples/archify-repo.architecture.json --json

```

### Rendering the HTML Artifact

```javascript
import { deliver } from 'archify/bin/archify.mjs';

await deliver(
  'architecture',
  result,
  result.meta.output,  // e.g., './archify-repo.html'
  { open: false }
);

console.log('HTML diagram written to', result.meta.output);

```

The `deliver` command produces a **self-contained HTML file** with embedded assets—no external dependencies required.

One-liner version:

```bash
node archify/bin/archify.mjs deliver architecture examples/archify-repo.architecture.json ./archify-repo.html --open

```

---

## Practical Interpretation: Walking Through an Example

The file [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json) demonstrates full feature usage. Here's how to interpret it:

1. **Identify the system** – Check `meta.title` ("Archify") and `meta.subtitle` for context.

2. **Trace the main data flow** – Follow emphasized connections (`variant: "emphasis"`) from "You" → "Agent Hosts" → "JSON IR" → "Renderers" → "HTML Artifact". These highlight the core pipeline.

3. **Notice optional paths** – Dashed connections show CI packaging and quality gates that run conditionally.

4. **Locate the core boundary** – The `security-group` named "archify/skill package" wraps the pipeline components, marking the trusted execution zone.

5. **Read the cards** – Three cards ("Agent loop", "Render path", "Quality gates") provide narrative context for design decisions.

6. **Verify grounded claims** – Pick any component, examine its `sources` array, and cross-reference with the actual file paths and line ranges in the repository.

---

## Key Questions Answered by Archify Results

| Question | Where to Look | Specific Field(s) |
|----------|-------------|-------------------|
| What are the primary components? | `components` array | Filter by `type` |
| How does data move? | `connections` array | `from`, `to`, `fromSide`, `toSide`, `via` |
| Where are trust boundaries? | `boundaries` array | `kind: "security-group"` |
| Which source lines support a node? | Component object | `sources` (file, line_start, line_end) |
| What's the critical path? | `connections` array | `variant: "emphasis"` |
| How was this diagram laid out? | `layout` object (if present) | `grid`, `cols`, `gapX`, `gapY` |

---

## Summary

- **Archify analysis results are strict JSON** validated against [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json)—no ambiguity, no missing fields.

- **Six sections define every diagram**: `meta` (metadata), `layout` (positioning), `components` (nodes), `boundaries` (groups), `connections` (edges), and `cards` (narratives).

- **`sources` arrays ground claims in code**—always traceable to file paths and line numbers.

- **Use the CLI** (`archify/bin/archify.mjs`) to validate with `validate` and render with `deliver`.

- **Study [`examples/archify-repo.architecture.json`](https://github.com/tt-a1i/archify/blob/main/examples/archify-repo.architecture.json)** for a complete, production-grade reference.

---

## Frequently Asked Questions

### What file format does Archify use for analysis results?

Archify uses **typed JSON** with a strict schema. Every analysis result is a [`.architecture.json`](https://github.com/tt-a1i/archify/blob/main/.architecture.json) file that validates against [`archify/schemas/architecture.schema.json`](https://github.com/tt-a1i/archify/blob/main/archify/schemas/architecture.schema.json). This ensures machine readability and prevents malformed outputs from reaching renderers.

### How do I verify an Archify analysis result is correct?

Run the built-in validator through the CLI: `node archify/bin/archify.mjs validate architecture <file> --json`. The validator returns a receipt with either an empty `diagnostics` array (valid) or detailed error objects with JSONPath pointers to violations.

### Can I trace Archify components back to actual source code?

Yes. Every component includes a `sources` array containing objects with `file`, `line_start`, and `line_end` properties. These map directly to repository locations, enabling **grounded architecture** where visual claims are verifiable against implementation.

### How do I share a specific view of an Archify diagram without manual navigation?

Use `meta.views` definitions to encode URL fragments like `#focus=skill&reach=downstream`. Append these to the HTML artifact URL—recipients will open the exact same focused perspective with the same lens and route settings.