Turning a Codebase into a Verifiable System Map: How Archify Makes AI-Generated Architecture More Than Pretty

When a team asks AI to draw a system architecture diagram, the most common problem is not that the result looks bad. It is that the result cannot be trusted: components may be missing, arrows may be visual guesses, and after an update it can be difficult to tell what really changed. tt-a1i/archify takes a different approach. It is neither another Mermaid theme nor a general drawing editor. It is an Agent Skill in which a coding agent produces a typed JSON intermediate representation (IR), and a Node.js toolchain validates and deterministically compiles it into HTML/SVG.

This article is based on Archify's GitHub source and official documentation. It explains the working model, validation gates, interactive reading features, and why the project fits everyday development workflows. The facts and commands reflect the main branch and the v2.17.0-dev.1 version shown in the README when checked on September 11, 2026. GitHub star counts change over time; the repository had about 58,020 stars at that time.

The short version: Archify addresses communication trust

Archify's main value is not arranging boxes more attractively. It turns the relationships claimed by a diagram into data that can be checked. The workflow is:

1. The agent creates typed JSON IR from a description or repository source.

2. Validators check the schema, layout, HTML/SVG, routes, and label-to-route clearance.

3. A passing IR is rendered as self-contained HTML and can be exported as PNG, SVG, WebM, or a 1200×630 share card.

4. Readers can search nodes, trace authored upstream/downstream reach, inspect exact routes, or play finite guided stories.

5. Only a validated candidate replaces the last trusted artifact; when a candidate fails, the preview keeps the last-good artifact.

This design keeps AI uncertainty in the candidate-generation stage and gives delivery responsibility to deterministic checks. Archify does not claim to know live traffic, and it does not invent runtime impact. It presents topology that has been authored and has passed the applicable rules.

Installation: connect the Skill to a coding agent

The shortest installation path in the README is:

npx skills add tt-a1i/archify -g

The documented integrations include Cursor, Claude Code, Codex CLI, and OpenCode. To try it without a global installation:

npx skills use tt-a1i/archify@archify --agent codex

After installation, no repository is required to begin. Describe a system directly in an agent conversation:

Use Archify to draw: Browser -> API -> Redis cache -> PostgreSQL fallback.

For source evidence, open a repository and ask the agent to analyze the source and create a high-level runtime architecture diagram. The official quick start recommends limiting the number of core components, specifying a primary path, external dependencies, and trust boundaries, and placing supporting detail in cards instead of adding unlimited edges.

Five diagram types for five kinds of questions

Archify separates the reading purpose instead of putting everything into one architecture diagram:

Architecture answers which components, services, storage systems, and boundaries exist.
Workflow explains the order, branches, and exceptions in CI/CD, approvals, tool calls, and runbooks.
Sequence explains how one API call, cache fallback, authentication flow, or asynchronous interaction unfolds over time.
Data Flow explains where data comes from, how it is transformed, where it is stored, and where PII or other sensitive boundaries appear.
Lifecycle explains states, waits, retries, cancellation, and terminal outcomes.

This split is practical. When deployment topology, request timing, data lineage, and failure retries all share one canvas, the reader often sees only complexity. Choose the question first, then choose the diagram type, and the result is much more likely to become a communication tool.

Validation gates: beauty is not a delivery condition

Archify describes validation as atomic validation before delivery. The workflow is not “render once and finish.” The candidate must pass a sequence of rules before replacing the last trusted version. Common commands include:

cd archify
node bin/archify.mjs doctor
node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs validate workflow examples/agent-tool-call.workflow.json --quality showcase --json
node bin/archify.mjs deliver workflow examples/agent-tool-call.workflow.json /tmp/workflow.html --quality showcase --open --json

When validation fails, validate --json and deliver --json return diagnostics containing stable rule codes, the subject, measured evidence, and supported fixes. That is more useful than a Node stack trace or asking an agent to “try again”: repairs are limited to actions explicitly supported by the diagnostics. The documentation also requires a separate visual review, so automated rules are not treated as a replacement for design review.

Archify also provides a preview mode. It watches one JSON file on a loopback interface and reloads only after the candidate passes every gate. If the saved content is incomplete or invalid, the screen keeps the previous verified diagram. This is better suited to long editing sessions than a preview that constantly displays half-finished output.

Architecture Delta: turn PR review into reading change

Architecture diagrams are most likely to become stale after a system changes. Archify's Architecture Delta accepts validated Before, Delta, and After snapshots. It summarizes changes as added, removed, changed, moved, and rerouted facts, and produces a machine receipt.

node archify/bin/archify.mjs compare architecture base.json head.json architecture-delta.html --json

This does not automatically decide that a PR is safe or that a change will affect a particular service. Archify explicitly leaves impact, risk, and merge safety to the reviewer. Its job is to organize differences in authored facts so reviewers can inspect the change first and then decide which source code, tests, and deployment evidence to examine.

The key to interaction: do not fabricate topology

A static image shows an outcome. Archify's interactive viewer constrains reading operations to nodes and relationships that are already authored. The README lists node search, revision-verified source links, authored upstream/downstream reach, exact route inspection, semantic role comparison, and finite named chapters.

The qualifiers matter: it is authored reach, not runtime impact; it is an exact route, not a plausible path improvised by a model; it is revision-verified source, not a vague repository link. If a diagram lacks authored owners, region placement, private database scope, or named crossings, the deployment-ownership profile fails closed instead of guessing. The official Proof Lab contains 11 checked-in scenarios, JSON sources, named views, and validation receipts. They show how guided stories, route probes, and semantic lenses can support different reading goals without drawing a separate diagram for each one.

Repository evidence: use AI with explicit boundaries

When source evidence is needed, Archify marks Architecture nodes with SRC n and opens Git-verified files and line ranges pinned to one public commit. This is useful for code review and onboarding because a reader can move from a component in the diagram to a concrete file and line range.

It is still not runtime observability. A source-level call chain does not mean that every production request follows that path. A diagram passing validation does not prove that deployment permissions, network policy, or data quality are correct. A safer practice is to treat Archify as a source-grounded communication artifact, and to state the checked commit and scope clearly in the PR, article, or design document.

A minimal team workflow

Start with a small case that does not depend on a real repository:

node archify/bin/archify.mjs guide "Show an API request with Redis cache miss"
node archify/bin/archify.mjs guide "Map Kafka topics, consumer groups, replay, and DLQ" --json

Then use this rhythm:

1. Define the question the diagram must answer in one sentence.

2. Generate the first typed JSON IR in the agent conversation.

3. Run validate --json and read the machine-readable diagnostics.

4. Apply only the supported fixes in diagnostics[], within the correction limit.

5. Use deliver to create the HTML beside the JSON, and commit the JSON and validation receipt.

6. Have a reviewer perform an independent visual review and source review.

7. For the next change, use the validated snapshot as Before and generate an Architecture Delta.

This workflow is especially useful for cross-functional communication. Backend engineers can inspect routes, platform engineers can inspect boundaries, and product or engineering leaders can use a guided story to understand the main path without reading the entire repository first.

Limitations to include in an evaluation

Archify's constraints are important too:

It is not a general-purpose drawing editor and cannot replace tools that require free-form drawing.
It does not read live infrastructure and should not be treated as a runtime topology or impact-analysis system.
Strict profiles such as deployment-ownership may reject delivery when evidence is missing. That is expected fail-closed behavior, not merely a UI error.
Diagram quality still depends on the prompt, source scope, and authored IR. A deterministic renderer can make the input reproducible; it cannot supply architecture decisions that were never written down.
The README identifies a development version. Before adopting it in a production process, pin the version and preserve the JSON, receipt, and output artifact in CI.

Conclusion: make the architecture diagram reviewable

The real problem with AI-generated architecture diagrams is not just layout. When arrows can be misread, system changes lack a comparable baseline, and previews show unverified candidates, teams need a toolchain with explicit boundaries around what may be claimed.

Archify's answer is typed JSON IR, deterministic rendering, atomic validation, last-good preview, and source evidence. It does not promise to understand every production behavior; instead, it makes that limitation visible. For teams using Cursor, Claude Code, Codex CLI, or OpenCode, the pattern of “let the agent generate a candidate, then let rules decide whether it can be delivered” is more valuable than merely producing a more elaborate picture.