Archify Explained: Verified Diagrams That Don't Invent Topology

Ask an AI assistant to diagram your system and there's a real risk it draws something plausible-looking that's quietly wrong — a connection that doesn't exist, a component relationship invented to fill a gap in what it actually knows. Archify is a Claude Code, Cursor, Codex CLI, and OpenCode Agent Skill built specifically to close that gap: every diagram goes through a validation pipeline before it's ever shown to you, and the interactions built on top of it — tracing upstream and downstream reach, comparing roles, replaying a guided story — are constrained to reuse only the relationships that were actually authored into the diagram's source data.

That matters because architecture diagrams are trust documents. People use them to onboard new engineers, to argue about a refactor, and to decide where a security boundary sits. A diagram generated by a background coding agent or a chat assistant that invents one edge is worse than no diagram, because it looks authoritative. Archify treats a verified architecture diagram as an output that has to pass checks, the same way code has to pass tests.

This explainer covers how Archify's five-stage validation pipeline works, the five diagram types it supports, its snapshot diff mode for architecture review, evidence-backed nodes pinned to real source lines, how to install and prompt it, the opt-in deployment review profile, and how it compares with Diagram Design.

The Core Bet: Validate Before Delivery, Every Time

Archify's generation pipeline has five explicit stages: an agent generates a typed JSON intermediate representation from your description, bundled validators and layout rules check that source, an optional local preview loop shows only revisions that passed validation, a final delivery step atomically renders and re-checks the artifact before it replaces anything on disk, and only then can the agent iterate further. That "atomic validation before delivery" step is the load-bearing design decision — schema checks, layout checks, HTML/SVG checks, route checks, and label-to-route clearance checks all have to pass before a new diagram is allowed to overwrite the last known-good one. A failed validation doesn't produce a broken diagram silently shipped anyway; it returns a structured, machine-readable diagnostic with the exact rule that failed and the specific subject to fix, rather than a generic error or an unstructured retry.

Five Diagram Types, One Underlying Discipline

Archify covers architecture, workflow, sequence, data-flow, and lifecycle diagrams, each rendered to a self-contained HTML file with four visual presets and optional finite motion — genuinely interactive, not a static export. The interaction layer is where the "don't invent topology" principle actually gets enforced: searching nodes, opening source-verified file references, tracing authored reach in either direction, comparing roles, and playing a guided walkthrough all reuse the relationships that were actually put into the diagram's source data. There's no live path-finding or synthetic reasoning happening at view time that could surface a connection nobody actually authored — what you can explore is bounded by what was validated at generation time.

Diffing Two Snapshots Is the Feature Worth Building a Workflow Around

Beyond generating a fresh diagram, Archify can compare two validated snapshots and produce a Before / Delta / After view — showing exactly what was added, removed, changed, moved, or rerouted between them. That's a genuinely useful primitive for reviewing an architecture change before it merges: instead of eyeballing a pull request and trying to reconstruct what actually changed structurally, you get a diagram-level diff grounded in the same validated data model as the diagrams themselves. For any team doing regular architecture review, this is the feature most worth evaluating on its own, independent of whether Archify becomes the default diagram tool for everything else.

Evidence-Backed Nodes, Only When You Ask For Them

For architecture diagrams specifically, nodes can be marked as evidence-backed and opened directly to the Git-verified file and line range they're pinned to, tied to one specific public commit — a direct, checkable link between "this is what the diagram claims" and "this is the actual code that claim is based on." Notably, this is opt-in: ordinary artifacts stay source-free, so the added rigor of source-pinning is available for the cases that need it (a real architecture review, an onboarding doc someone will actually rely on) without forcing every quick diagram through the same overhead.

Benefits of Archify

Diagrams that cannot quietly invent connections

The central benefit is trust. Because every interaction reuses only relationships authored into the validated source, a reader exploring the diagram cannot stumble onto an edge the model guessed at. For architecture diagrams that inform security boundaries or refactor decisions, removing that class of error matters more than any visual feature. Reviewers can argue about whether the authored model is right, instead of first discovering that the picture contains a link nobody described.

Failures that tell the agent exactly what to fix

When validation fails, Archify returns a structured diagnostic naming the rule and the subject that broke it. The agent can make a targeted correction rather than regenerating the whole diagram and hoping the next attempt is better. That keeps iterations short and stops a broken diagram from replacing the last known-good one, since delivery is atomic and only happens after every check passes.

Architecture review grounded in structure, not pixels

Snapshot diffing turns "what changed in this design?" into a Before / Delta / After view of added, removed, moved, and rerouted elements. Because both snapshots share the same validated data model, the comparison reflects structural changes rather than layout noise. Teams get a review artifact they can attach to a pull request and discuss concretely.

A checkable link from claim to code

Evidence-backed nodes pin a component to a specific file, line range, and public commit. Anyone doubting what the diagram says can open the source it was based on. That makes diagrams usable as onboarding material and review evidence, not just illustrations, while the opt-in design keeps quick sketches lightweight. The commit pin also makes it obvious when a diagram is describing an older version of the code.

Shareable, self-contained output

Each diagram is a single HTML file with interactions built in, and specific views can be shared as stable deep links. A reviewer can link straight to a route probe or a focused node in a comment instead of describing it in prose, and the file opens without extra tooling. There is no hosted service to sign into, so the diagram travels with the review wherever it is posted.

Archify Use Cases

Onboarding engineers to an existing codebase

New team members often learn a system from diagrams that were accurate once and have drifted since. Generating an architecture diagram with evidence-backed nodes ties each component to the code it represents, at a specific commit. A new engineer can move from the overview to the actual source in one click, and the team knows the diagram reflects a point in time it can name.

Reviewing architecture changes before merge

Structural changes are hard to see in a pull request made of dozens of file edits. Teams can generate validated snapshots before and after the change and use the diff view to show what was added, removed, or rerouted. Reviewers discuss the design change itself, and the diff becomes a durable record of why the structure moved. Months later, anyone asking when a service gained a new dependency can find the diff attached to the change that introduced it.

Documenting request paths and fallbacks

Sequence diagrams suit API calls, cache misses, and authentication flows, such as a request travelling from browser to web app to API to session lookup with a database fallback. Writing these out with named callers, callees, and returns makes the behaviour explicit, and the route probe lets readers inspect an exact authored path rather than a guessed one. Deep links to a specific route make it easy to point a teammate at the exact step under discussion.

Preparing a production deployment review

With the opt-in deployment-ownership profile, an architecture diagram must name owners, region placement, private database scope, and boundary crossings before it passes. Teams use it as a completeness check before a review meeting, so gaps surface as validation failures instead of awkward questions in the room. It checks the authored description, not the live infrastructure.

Explaining pipelines and data handling

Data-flow and workflow diagrams fit CI/CD pipelines, approval chains, lineage, and PII handling. Describing sources, transforms, stores, and boundaries forces the author to be specific about where sensitive data travels, and the result can be presented with the guided story mode to walk stakeholders through it in order.

Getting Started With It

Installation is a single command — npx skills add tt-a1i/archify -g for a global install, with an explicit non-interactive form for Cursor if you're scripting a setup rather than clicking through prompts. There's also a no-install path for trying it once: npx skills use tt-a1i/archify@archify --agent codex runs it for a single session without registering it permanently. Beyond Claude Code, Cursor, Codex CLI, and OpenCode, it also installs into Raven — EverMind's memory-first agent harness — via a manual ZIP extraction rather than the skills CLI. Once installed, the actual prompt is plain language: the README's own examples scope the request directly — 8 to 12 core components, one primary path, external dependencies, and trust boundaries for an architecture diagram, or a specific request/response chain (browser to web app to API to session lookup to database fallback) for a sequence diagram — pushing supporting detail into cards rather than adding more edges to keep a diagram legible. Refining after the first draft is conversational: follow-up requests like "add Redis" or "move auth to the left" keep the typed source available for targeted, incremental changes rather than a full regeneration.

Picking the Right Diagram Type for the Job

Since Archify covers five distinct diagram types rather than one general-purpose canvas, matching the type to the actual question you're trying to answer matters more than it would with a single flexible format. Architecture diagrams suit components, services, storage, and trust boundaries, and want scope, core components, and the primary path specified in the prompt. Workflow diagrams fit CI/CD pipelines, approval chains, and runbooks, and want participants, ordering, branches, and exception paths spelled out. Sequence diagrams are for API calls, cache fallbacks, and auth or async traces, and want callers, callees, returns, and timing named explicitly. Data Flow diagrams suit pipelines, lineage, and PII handling, and want sources, transforms, stores, and boundaries specified. Lifecycle diagrams cover states, retries, waits, and terminal outcomes, and want the actual states, events, and retry or cancellation paths described. For anyone unsure which fits, the project ships an interactive scenario guide, and the same zero-dependency logic is available from the command line — node archify/bin/archify.mjs guide "Show an API request with Redis cache miss" returns a recommendation without needing an agent session running at all.

An Opt-In Profile for Production Deployment Review

Architecture diagrams specifically can enable an additional, opt-in engineering profile called deployment-ownership, built for reviewing a production deployment rather than a general system overview. It fails closed rather than silently passing: if owners, single-region placement, private database scope, or named boundary crossings are missing from what was authored, validation rejects the diagram instead of shipping an incomplete one. It's never enabled by default, and it's explicit about validating authored facts only — it checks that what you told it to diagram is internally consistent and complete against that specific checklist, not that it matches your actual live infrastructure. That distinction matters: passing this profile confirms the diagram is a complete, honest representation of what was described to it, not an independent audit of what's actually running in production.

Exploring a Diagram Without Inventing Anything

Beyond generation, the interaction layer has a fairly deep keyboard-driven surface: / searches and focuses a node, R probes a directed route and inspects its exact authored path, L compares one or two semantic roles side by side, M opens a live overview radar, P plays a guided story with [ and ] moving between chapters, and F enters a distraction-free presentation stage. Every one of those stays grounded in what was actually authored — a route probe reports the shortest authored directed path, not a live shortest-path calculation over some inferred graph. States are also shareable as stable deep links (#focus=<id>, #route=<source>~<target>, #lens=<kind>~<kind>, #view=<view-id>), so a specific reading of a diagram can be linked directly in a PR comment instead of described in prose. Reader-driven motion in these views is finite, respects prefers-reduced-motion, and never appears in a canonical export.

Archify vs Diagram Design

Archify and Diagram Design both fight the same generic-AI-diagram problem, but from different angles worth understanding before picking one. Diagram Design's core discipline is editorial: a fixed design system, brand-token extraction from your own website, and 27 diagram types built for visual consistency and polish. Archify's core discipline is epistemic: a typed, validated intermediate representation, atomic delivery gates, and interactions that can't invent a relationship the source data doesn't actually contain. If the priority is a diagram that looks like it belongs on your brand's site, Diagram Design is the more direct fit. If the priority is a diagram you can trust wasn't quietly fabricated — especially one traced from an actual codebase, or one being diffed for an architecture review — Archify's validation-first design is built specifically for that case. Nothing stops a team from using both for different jobs.

The table shows two tools optimising for different failure modes. Diagram Design assumes the main problem with AI diagrams is that they look generic and inconsistent, so it invests in a design system, brand extraction, and a wide catalogue of diagram types. Archify assumes the main problem is that AI diagrams can be wrong while looking authoritative, so it invests in a typed intermediate representation, validators, and interactions that cannot step outside what was authored.

That difference shows up in what each tool is best used for. A marketing page, a product explainer, or a slide that needs to match your brand benefits from Diagram Design's polish and breadth. An architecture review, an onboarding document tied to real code, or a deployment checklist benefits from Archify's verification and its diff mode, even though it offers fewer diagram types and less visual customisation.

Neither tool checks a diagram against your live systems. Archify proves internal consistency with what was described, and Diagram Design produces consistent visuals from what was described. For teams that need both trust and polish, running them side by side for different documents is a reasonable choice rather than a compromise.

What to Weigh Before Adopting It

• The validation discipline is the reason to use this over a generic diagram prompt — if you're not going to lean on evidence-backed nodes, snapshot diffing, or the guarantee against invented topology, a lighter-weight tool might be enough for casual diagramming.
• The local preview loop is explicitly loopback-only and off by default — it binds to 127.0.0.1, watches one file, and stops with Ctrl-C, which is a reasonable, conservative default for anything running a local server as part of a CLI tool.
• It's positioned as a communication artifact tool, not a general drawing editor — the README says so directly. If you need freeform diagram editing beyond what's authored through the described system, this isn't built for that.
• It's a young, single-maintainer-led project (created 2026) with real sponsor backing and steady releases — a good sign of momentum, worth pinning a version for anything you depend on for recurring architecture documentation.

Common Archify Mistakes

Treating a passing diagram as an infrastructure audit

Validation confirms a diagram is consistent and complete against what was authored. It does not compare the diagram with what is running in production. Teams that present a validated diagram as proof of their live topology are claiming more than the tool checks. If the description given to the agent was wrong, the diagram will be a faithful, validated picture of the wrong system.

Cramming every component into one diagram

The project's own prompt examples keep architecture diagrams to a core set of components and one primary path, with supporting detail pushed into cards. Asking for every service, queue, and dependency at once produces a dense diagram that passes validation but communicates little. Split large systems into several focused diagrams, or use a different diagram type for detailed flows.

Picking the wrong diagram type

An API call with a cache fallback described as an architecture diagram loses the ordering and returns that make it understandable. A pipeline described as a sequence diagram loses its branches. Matching the type to the question, or running the bundled guide when unsure, saves several rounds of revision.

Skipping evidence-backed nodes where they matter

Because evidence pinning is opt-in, it is easy to forget it on exactly the diagrams people will rely on. Onboarding material and architecture reviews are the cases where a link from node to commit and line range pays for its overhead. Quick sketches can stay source-free, but a diagram that will be cited in a decision should carry its evidence.

Leaving the version unpinned

The project is young and releases steadily. Recurring documentation built on an unpinned version may change behaviour or output between runs. Pin the version used for anything that is regenerated regularly, and upgrade deliberately.

Archify Best Practices

• Scope the prompt explicitly. Name the core components, the primary path, external dependencies, and trust boundaries for architecture diagrams, or the callers, callees, and returns for sequence diagrams. Specific prompts produce diagrams that need fewer revisions and validate on the first or second pass.
• Refine incrementally. Use follow-up requests such as adding a cache or moving a component, which keep the typed source and make targeted changes, rather than restarting from a blank prompt each time.
• Use the diff for every significant structural change. Generate a snapshot before and after an architecture change and attach the Before / Delta / After view to the pull request, so reviewers discuss the structural change directly.
• Pin evidence on diagrams people will rely on. Turn on evidence-backed nodes for onboarding and review diagrams so every important claim links to the code behind it at a specific commit.
• Enable the deployment-ownership profile before production reviews. Let validation reject diagrams missing owners, region placement, database scope, or boundary crossings, and fix the gaps before the meeting rather than during it.
• Use the bundled guide when the diagram type is unclear. Describe the scenario to the command-line guide and let it recommend a type before you spend tokens on a generation that will need to be redone in a different format.
• Read validation diagnostics before re-prompting. The structured error names the rule and subject that failed. Fixing that specific issue is faster and more predictable than asking the agent to "try again" and hoping the next attempt passes.
• Share deep links instead of screenshots. Link to a focused node, route, or view in review comments so others see the exact state you are referring to, with its interactions intact.
• Keep the preview loop local and short-lived. The preview server binds to the loopback address and is off by default; start it when iterating and stop it when finished, consistent with how it was designed.

Practical Takeaway

Archify is a strong example of applying real software-engineering discipline — schema validation, atomic writes, structured error reporting — to a problem (AI-generated diagrams) that's usually treated as purely a design or prompting exercise. For teams that need architecture documentation or code review artifacts they can actually trust weren't quietly hallucinated, the validation pipeline and snapshot-diff feature are worth evaluating specifically, independent of whether you adopt it as your default diagramming tool.

Teams building AI-assisted documentation or architecture-review workflows that need output they can actually verify can get hands-on help from Woyce Technologies.

FAQ

What is Archify?

Archify is an Agent Skill for Claude Code, Cursor, Codex CLI, and OpenCode that generates interactive architecture, workflow, sequence, data-flow, and lifecycle diagrams as self-contained HTML, validated through a schema and layout pipeline before delivery. The point is accuracy rather than decoration: interactions inside the diagram can only reuse relationships that were authored and validated, so the tool cannot surface a connection that nobody actually described or traced from the codebase.

How does Archify prevent diagrams from showing incorrect information?

Every diagram is generated as a typed JSON intermediate representation that passes schema, layout, HTML/SVG, and route validation before it's delivered, and all interactive exploration — reach tracing, role comparison, guided stories — is restricted to relationships that were actually authored into that validated source, rather than inferred at view time.

Can Archify compare two versions of an architecture diagram?

Yes — it can diff two validated snapshots and produce a Before / Delta / After view showing exactly what was added, removed, changed, moved, or rerouted, which is useful for reviewing architecture changes before a merge. Because both snapshots go through the same validation pipeline, the diff reflects structural changes in the authored data model rather than visual differences in layout, which makes it practical to attach to a pull request.

Is Archify free to use?

Yes, it's MIT-licensed and open source, installable via npx skills add tt-a1i/archify -g. You can also try it once without installing via npx skills use. The only running costs are whatever your AI coding assistant normally charges for the tokens used to generate and refine diagrams, since Archify runs inside that agent session.

What's the difference between Archify and Diagram Design?

Diagram Design focuses on editorial polish and brand-matched visual consistency across 27 diagram types. Archify focuses on validated, evidence-backed accuracy — a typed data model, delivery gates, and interactions that can't invent topology the source data doesn't contain. They solve related but distinct problems and can be used for different purposes.

Can Archify link a diagram back to the actual source code?

Yes — architecture diagram nodes can be marked evidence-backed and opened directly to the Git-verified file and line range they're based on, pinned to a specific commit, though this is opt-in rather than automatic for every diagram. Keeping it optional means quick sketches stay lightweight, while diagrams used for real architecture review or onboarding documentation can carry a checkable link from every claim back to the code it describes.

Which AI coding tools does Archify work with?

Archify installs as an Agent Skill for Claude Code, Cursor, Codex CLI, and OpenCode through the skills CLI, and into the Raven agent harness through a manual ZIP extraction. Once installed you prompt it in plain language, describing scope, core components, the primary path, and boundaries. It also ships a command-line guide that recommends a diagram type for a described scenario without needing an agent session, which is useful when you are unsure whether you need an architecture, sequence, or data-flow view.

Conclusion

AI assistants are good at producing diagrams that look right. The problem Archify addresses is that looking right is not the same as being right, and an invented connection in an architecture diagram can mislead a review, an onboarding, or a security discussion. Archify's answer is engineering discipline: a typed intermediate representation, validators that must pass before anything is delivered, and interactions that can only reuse authored relationships.

The features most worth evaluating are the snapshot diff for architecture review and evidence-backed nodes pinned to specific commits and line ranges. Together they make a diagram something you can check rather than trust on faith. If you mostly need polished, brand-consistent visuals, Diagram Design may be a better fit, and the two can coexist.

Keep the caveats in mind. Validation proves a diagram is consistent with what was authored, not that it matches your live infrastructure. It is a young project, so pin a version for recurring documentation. And for a broader view of how agents use skills like this, see our guide to context engineering.

If you want AI-assisted documentation or review workflows your team can actually verify, book a call with Woyce.