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.
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.
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.
How It Compares to 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.
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.
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.
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.
Is Archify free to use?
Yes, it's MIT-licensed and open source, installable via npx skills add tt-a1i/archify -g.
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.