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

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, 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

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

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:

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

Rendering the HTML Artifact

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:

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 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—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 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 file that validates against 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.

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