How Archify's Typed JSON IR Ensures Reproducible Diagrams: 5 Mechanisms Explained

Archify guarantees reproducible diagrams by validating every input against strict JSON schemas, generating deterministic content-derived identifiers, and atomically delivering output only after all checks pass.

Archify's typed JSON IR (intermediate representation) serves as the single source of truth for all diagram generation. By treating the JSON file as an immutable contract rather than a loose configuration, the system eliminates randomness and ensures identical inputs always produce identical visual outputs. This article examines the five coordinated mechanisms that enforce this reproducibility in Archify according to the tt-a1i/archify source code.

---

Strict Typed Schemas Lock the Data Shape

Every diagram mode in Archify carries its own JSON schema that defines the exact structure, required fields, and permitted values.

The architecture.schema.json file constrains nodes, edges, layout hints, and metadata so that any deviation is caught during validation rather than during rendering. This prevents "silent" changes that could alter visual output without warning.

• Schema location: archify/schemas/architecture.schema.json
• Coverage: Architecture, Workflow, Sequence, Data Flow, and Lifecycle modes each have dedicated schemas
• Validation timing: Runs before any rendering begins, failing fast on contract violations

As the README states, "every renderer‑backed mode has a schema and reproducible source" (lines 20‑21).

---

Deterministic Identifiers Eliminate Randomness

Archify generates stable IDs for every fact—nodes, edges, and labels—during the validation phase. These IDs derive from the content itself, not from random seeds or incremental counters.

This content-addressing approach means:

• Re‑running the same JSON IR produces identical ID assignments
• Layout relationships remain consistent across regenerations
• "Deterministic exact‑ID Architecture Delta review" becomes possible (README lines 86‑88)

The deterministic ID system is foundational to version-controlled architecture reviews, where authors need confidence that changes reflect genuine content edits rather than rendering noise.

---

Atomic Validation Prevents Partial Output

Archify bundles multiple validators into a single atomic gate:

Validator	Purpose
Schema	Structural correctness against typed JSON IR
Layout	Spatial arrangement feasibility
Routing	Edge path validity
Label-to-route	Text placement against connection lines

All checks must pass before any artifact replaces the previous version. As documented in the README (lines 86‑89): "schema, layout, HTML/SVG, route, and label‑to‑route clearance checks must all pass before a showcase artifact replaces the last known good output."

If validation fails, the previous verified artifact remains visible. This eliminates "flaky" diagrams and gives users confidence that displayed output represents a fully-validated state.

---

Last-Good Preview Loop Preserves Verified Output

The desktop preview system watches a single JSON file and only refreshes after a new candidate passes every validation gate.

From the README's "Preview (optional)" section (lines 96‑103): developers iterating on source files keep their last-good diagram visible while working through errors. This guarantees that the visible output always stems from a fully-validated JSON IR, not from an intermediate broken state.

---

Self-Contained Output Enables Portable Reproduction

Final artifacts embed the original JSON IR (or its deterministic derivative) directly:

# Generate a reproducible Architecture diagram from typed JSON IR

cat > architecture.json <<'EOF'
{
  "meta": { "visual_preset": "signal-flow" },
  "nodes": [
    { "id": "frontend", "type": "service", "label": "Web Front‑end" },
    { "id": "api",      "type": "service", "label": "API Server" },
    { "id": "db",       "type": "storage", "label": "PostgreSQL" }
  ],
  "edges": [
    { "source": "frontend", "target": "api", "label": "HTTP" },
    { "source": "api",      "target": "db",  "label": "SQL" }
  ]
}
EOF

# Validate against schema

node archify/bin/archify.mjs validate architecture architecture.json --quality showcase --json

# Deliver deterministic HTML + PNG

node archify/bin/archify.mjs deliver architecture architecture.json out.html --open --json

Because the HTML contains the validated IR, diagrams reproduce identically without external dependencies. Share cards (PNG/SVG/WebM) derive from this deterministic HTML, ensuring a given JSON IR always yields the same shareable asset (README lines 20‑21).

Verifying Reproducibility

# First generation

node archify/bin/archify.mjs deliver architecture architecture.json out1.png

# Second generation with identical source

node archify/bin/archify.mjs deliver architecture architecture.json out2.png

# Confirm byte-identical output

diff out1.png out2.png   # → no differences

---

Key Source Files

Path	Role
archify/schemas/architecture.schema.json	Typed JSON structure definition for Architecture diagrams
archify/SKILL.md	Contract, validation flow, and atomic delivery specifications
archify/references/delivery-contract.md	Detailed delivery-step guarantees
README.md (Typed JSON IR section)	End-user reproducibility summary
examples/web-app.architecture.json	Version-controlled IR samples

---

Summary

• Typed schemas in archify/schemas/*.schema.json enforce structural contracts before rendering begins
• Content-derived deterministic IDs guarantee identical identifier assignment across runs
• Atomic validation bundles schema, layout, routing, and label checks into a single gate
• Last-good preview loop preserves verified output during iterative development
• Self-contained artifacts embed the original IR for portable, dependency-free reproduction

Together these form a reproducibility pipeline: Typed JSON IR → Schema validation → Deterministic IDs → Atomic delivery → Immutable, shareable artifacts.

---

Frequently Asked Questions

What makes Archify's JSON "typed" compared to standard JSON?

The JSON is validated against strict JSON Schema definitions (archify/schemas/*.schema.json) that specify required fields, value types, and permitted enums for each diagram mode. This typing catches structural errors before rendering rather than allowing malformed data to produce unpredictable output.

Can two different JSON files ever produce identical diagrams?

Yes, if they describe semantically equivalent architectures with the same node content, edge relationships, and layout hints—regardless of key ordering or optional field presence. The deterministic ID generation hashes content, so equivalent content yields equivalent identifiers and layouts.

What happens if validation passes for schema but fails for layout?

The atomic delivery mechanism rejects the candidate entirely. The previous verified artifact remains visible, and no new HTML/SVG/PNG is written. This prevents partially-validated diagrams from entering the output stream.

Is the reproducibility guarantee limited to specific output formats?

No. The guarantee extends through the entire chain: validated JSON IR produces deterministic HTML, which generates deterministic PNG, SVG, and WebM share cards. Any format derived from the validated IR inherits the reproducibility property.

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