Archify: Verifiable Architecture Diagrams Generated by AI Agents
Ask an AI agent to diagram a codebase, and there is a good chance it will fill in the gaps with things that are not actually there. Because these models have seen thousands of system architectures, they can produce diagrams that look convincing while quietly inventing components such as Kafka, Redis, or extra services that never appear in your repository. The result may look like your architecture, but it is not necessarily grounded in your code.
Archify takes a different approach. Instead of treating architecture diagramming as a drawing task, it treats it more like a compilation pipeline. The AI first generates a typed JSON representation of the system. Archify then validates that representation against the actual codebase before passing it to a deterministic compiler, which renders the final result as an interactive, self-contained HTML file.
That separation is important because the AI does not control the final visual output. Its job is to describe the architecture in a structured format, while Archify handles validation and rendering. This makes the resulting diagram much easier to trust than one generated directly from an AI prompt.
Archify is MIT-licensed, has more than 36,000 GitHub stars, and works with tools including Cursor, Claude Code, Codex CLI, and OpenCode.
Why direct generation fails
Asking an agent to "draw the architecture" is asking it to perform a creative visual task. The model interpolates from its training data and produces something that resembles a plausible architecture for a system of this type. Components that don't exist in the repo appear in the diagram. Components that do exist get omitted. The result spreads misinformation about how your system actually works.
The three-step process
Generate: The agent analyzes the codebase and outputs a typed JSON file describing components (nodes) and their relationships (edges). It is not asked to draw anything. It produces a structured intermediate representation.
Validate: Archify takes the JSON and validates it for structural integrity, then cross-references each component against the actual source code with "repo evidence." If the agent invented a component, validation fails and produces an error with diagnostics and repair suggestions. Archify is fail-closed by design: badly formed JSON or invalid references never silently produce a broken diagram.
Render: Only after successful validation does the local compiler render the JSON into a self-contained HTML/SVG file. The rendering is deterministic: the same validated JSON always produces the same diagram. The AI had no hand in the visual output.
This separation plays to the strengths of each tool: the AI understands code and structure; the deterministic compiler handles layout and rendering.
Installation
Archify requires Node.js. Install it globally as an agent skill:
To try it without a permanent install:
Replace claude-code with cursor, codex, or opencode as needed. The packaged archify.zip also works without npm if your environment restricts it.
No API key, no account, no external service. The validator and renderer run entirely locally.
Prompting effectively
A vague prompt produces a repo tree with hundreds of nodes. The goal is a focused diagram that answers a single specific question. A high-quality Archify prompt:
The node limit forces focus. The "only include boxes that exist in this repo" instruction activates the repo-evidence validation. "If you cannot prove a component, omit it" tells the agent explicitly that omission is correct when evidence is absent. One question, one diagram.
The five supported diagram types are Architecture, Workflow, Sequence, Dataflow, and Lifecycle. You can specify the type in your prompt or let the agent infer it from the question.
The interactive viewer
The rendered HTML includes several navigation features. You can search for nodes by name, click any node to see its upstream dependencies and downstream consumers, and filter the graph to show only the relationships relevant to a specific service.
Diagrams can include "stories": predefined paths through the graph that animate a specific execution flow. For the cache-miss example, clicking "Play story" animates the path from the initial cache read, through the miss and recomputation logic, to the write-back step. This is more effective for explaining complex workflows than a static diagram.
Where repo evidence is available, clicking a node opens the corresponding lines of source code. The connection between the high-level diagram and the low-level implementation is direct.
Exports include PNG, dual-theme SVG, WebM motion capture, and a 1200×630 share card suitable for pull requests and Slack. Four visual presets are available: Signal Flow, Blueprint, Classic, and a fourth theme you can switch between from within the viewer.
Architecture diffs for code review
The JSON intermediate representation is the key to architecture diffs. Generate a validated JSON snapshot before a pull request and another after. Archify diffs the two files and produces a visual comparison that labels every change: Added, Removed, Moved, or Rerouted.
This gives reviewers an immediate high-level summary of what the PR changed architecturally, before reading a line of code. For PRs that add a retry mechanism, a new service, or reroute a data flow, this is substantially faster than piecing together the architectural impact from a diff of implementation files.
The LLVM analogy
Archify's creator describes it as a compiler for system maps, following the same pattern as LLVM: a frontend (the AI agent) parses the high-level input; an intermediate representation (the typed JSON) captures the system's structure in a standardized, validatable format; a backend (the HTML/SVG renderer) compiles the IR into the final artifact. The AI handles semantic understanding; the compiler handles everything after.
The JSON file is the source of truth. Committing it to your repository alongside the code gives you version-controlled architecture documentation that can be diffed, updated in the same commit as the implementation change, and regenerated into a new HTML at any point.
When not to use it
Archify is not the right fit for every diagramming workflow. Its interactive HTML output, for example, does not render inside GitHub README files. If you need a static architecture diagram that can live directly in Markdown, Mermaid.js is still the better choice.
It also helps to keep the scope narrow. Pointing Archify at a large monorepo and asking it to "map everything" will usually produce a diagram that is too dense to be useful. One question per diagram is not really a limitation, it is the design principle that keeps the output focused. If you cannot clearly state the single question the diagram should answer, the scope is probably too broad.
Before creating your first diagram, it is also worth looking through the Proof Lab on the project's GitHub page. It includes 11 checked-in scenarios with their JSON sources, named views, and validation receipts. It is one of the quickest ways to see what well-structured Archify output looks like and how narrowly each diagram is scoped.
This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.