Architecture diagrams become unreliable when the code changes but the diagram does not.
Archify approaches this problem by generating diagrams through your coding agent. The agent analyzes a repository, creates a typed JSON description of the system, and Archify validates and renders it as an interactive HTML/SVG diagram.
I tested it on an unfamiliar repository to answer four practical questions:
How accurately does it represent real code?
Can the diagram be regenerated when the code changes?
Is its architecture comparison useful during reviews?
What should you verify before trusting the output?
This post explains how to install Archify, generate a focused architecture diagram, check its claims against the repository, and avoid wasting model usage on an overly broad scan.
Archify is an agent skill for Claude Code, Cursor, Codex, and OpenCode.
The coding agent examines your repository or system description and writes a typed JSON representation of the architecture. Archify validates that representation and compiles it into a self-contained interactive HTML/SVG diagram.
It currently supports five types of diagrams:
This distinction matters: the coding agent interprets the repository, while Archify validates and renders the resulting structure.
Archify can catch malformed data, invalid references, layout problems, and several kinds of misleading visual routing. It cannot guarantee that the agent understood every architectural detail correctly.
You still need to review the result.
Archify requires Node.js 18 or newer.
Install the skill globally:
npx skills add tt-a1i/archify -g
Then open your project in a supported coding agent and use a scoped prompt such as:
Analyze this repository, then use Archify to create a high-level
runtime architecture diagram.
Show 8–12 core components, the primary request path, external
dependencies, storage, and trust boundaries.
Include source evidence where it is supported. Put secondary
details in cards instead of adding more edges.
The 8–12 core components
constraint is useful. Without it, a large repository can produce a technically detailed diagram that is difficult to read.
For a system that does not exist as code yet, you can also start with plain English:
Use Archify to draw this system:
Browser -> API gateway -> authentication service -> application API
-> Redis cache -> PostgreSQL fallback.
Show the trust boundary around the private services and database.
Every architecture diagram I have created manually was accurate for a limited time.
Then somebody renamed a service, moved a responsibility, or introduced another queue. The code changed, but the diagram did not.
An Archify diagram is not automatically synchronized with your repository. You must rerun the agent when the architecture changes.
The difference is that regeneration is much cheaper than manually redrawing the system.
Instead of deciding whether an old diagram is still trustworthy, I can regenerate it from the current repository and review the differences.
That makes architecture documentation feel more like a build artifact and less like a drawing somebody has to remember to maintain.
In evidence-backed architecture mode, components can reference repository files and line ranges pinned to a specific commit.
This is the part I found most valuable.
When I select a component, I can inspect the source evidence behind it instead of accepting a convincing-looking box. If a component is missing, I can search the repository and determine whether the agent overlooked it or whether the code genuinely is not there.
There is an important limitation, though.
Validation does not make hallucination impossible. The agent still authors the JSON structure, and repository evidence is optional and subject to supported repository conditions.
My rule is simple: I do not trust the diagram because it looks polished. I trust it only after I have checked the important nodes and relationships against the code.
A useful verification pass is:
The diagram accelerates understanding. It does not replace engineering judgment.
Archify diagrams can contain guided views that focus the reader on existing nodes and relationships.
A view might highlight:
These views are presentation layers over the authored topology. They do not silently create additional components or connections.
This makes the output useful for more than private exploration. I could see it working well for onboarding, design discussions, and explaining an unfamiliar service during a review.
Archify can compare two validated architecture snapshots and produce a Before, Delta, and After view.
From a checkout containing the Archify CLI, the command looks like this:
node archify/bin/archify.mjs compare architecture \
base.json \
head.json \
architecture-delta.html \
--json
Adjust the CLI path to match your installation.
The comparison can identify authored additions, removals, changes, movement, and rerouted relationships. It also produces a machine-readable receipt.
What it does not do is equally important.
The delta view does not determine:
It compares two authored architecture descriptions. It does not replace tests, observability, or human review.
Even with that limitation, seeing architectural additions and removals beside a pull request is something a static diagram rarely provides.
Archify itself is open source and free to run locally. The potentially expensive part is the coding agent analyzing your repository.
On a small application, that may be negligible. On a large monorepo, an unbounded request can consume significant model context and usage.
I now scope repository runs by:
I would not begin with “diagram the entire monorepo.”
I would start with something narrower:
Map the runtime architecture of packages/payments only.
Include its public entry points, database access, queues, external
providers, and calls to other workspace packages.
Limit the result to 12 primary components.
Smaller diagrams are cheaper to generate and easier to verify.
I would use it for:
I would not rely on it alone for:
Those require evidence beyond a diagram.
I tested Archify on both a plain-English system and a real repository. I also show two failure cases and how I checked the output.
Archify did not eliminate the work of understanding an unfamiliar codebase.
It changed the order of that work.
Instead of reading everything before I could form a useful mental model, I started with a structured map. I then used the code to confirm, correct, and deepen that map.
That was much faster than starting from a blank whiteboard.
The most useful feature was not that the diagrams looked good. It was that the underlying structure could be validated, regenerated, inspected, and compared.
Have your architecture diagrams ever survived longer than a month, or have you accepted that they eventually lie?