Archify
Archify Explained: Deterministic Architecture Diagrams for AI Coding Agents
Learn what Archify does, how typed JSON becomes verifiable HTML/SVG, and how to run its agent skill without inventing system topology.
What you will learn
- Explain the JSON-IR-to-render pipeline
- Create a bounded, source-traceable architecture map
- Preserve revisions and validation evidence for review
Before you start
- Basic Git and command-line usage
- Comfort reading a project README
You can explain the project, run its documented first step, and decide what to verify before adopting it.
Key takeaways
- Archify compiles typed JSON IR into deterministic, exportable diagrams.
- Validation and source tracing make the visual output reviewable rather than purely decorative.
- Pin the release and preserve the input revision when using generated maps in engineering work.
The short answer
Archify is a Node.js rendering and validation system for Cursor, Claude Code, Codex CLI, and OpenCode. Its README defines a clear boundary: an agent produces typed JSON intermediate representation, and Archify deterministically compiles that representation into HTML and SVG. The result is a system map that can be exported and checked rather than a diagram invented from a vague prompt.
That boundary matters for engineering teams. Archify is designed for architecture, workflow, sequence, data-flow, and lifecycle diagrams, with search, route tracing, guided stories, and Before/Delta/After comparison between validated snapshots. The project page reports stable version v2.16.0 for the captured snapshot, so article examples should pin the version they actually test.
How the workflow is grounded
The agent-facing workflow starts with a description or codebase context and produces an explicit JSON IR. Validation then becomes a gate before rendering. Interactions such as opening revision-verified source, tracing upstream and downstream reach, and comparing roles are useful because they expose the authored facts behind a visual edge instead of hiding them in a screenshot.
The README advertises five diagram types, four presets, dark and light themes, finite motion, and self-contained output. It also lists PNG, SVG, WebM, and 1200×630 share-card exports. These are output contracts to verify in a local run, not a reason to assume every input is semantically complete; a polished render can still describe an incomplete model if the source facts were missing.
Run the smallest useful experiment
The documented global installation path is `npx skills add tt-a1i/archify -g`. You can use the skill from a supported agent without cloning a target repository, then ask for a small architecture map with named nodes and explicit relationships. Keep the input bounded: a checkout, a service boundary, or one request flow is easier to validate than an entire organization.
For repeatable work, record the Archify release, agent host, input commit, selected diagram type, and export format. Compare the rendered output with the JSON IR and inspect one or two source links. If a node or route cannot be traced back to authored input, mark it as an unresolved fact instead of filling the gap with a plausible arrow.
When Archify is a good fit
Use Archify when a team needs architecture communication that remains inspectable during review: onboarding, design proposals, incident follow-up, or a before/after comparison of a refactor. The deterministic compiler is especially useful when diagrams are generated repeatedly in CI or attached to a change review.
It is less suitable as a substitute for a system inventory. A diagram is only as complete as the codebase context and authored JSON supplied to it, and a share card is not an audit trail. Keep the input revision, validation output, and rendered artifact together so a future reader can reproduce the map rather than trusting the image alone.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Install the skill with `npx skills add tt-a1i/archify -g`.
- 2
Give the agent one bounded codebase flow with named components and relationships.
- 3
Inspect validation results and trace representative nodes back to source.
- 4
Export the format you need and archive the input revision beside the artifact.
Copy-ready example
npx skills add tt-a1i/archify -g
# In a supported agent, request a bounded map:
# "Map the request flow from API gateway to worker and database; cite each edge."Frequently asked questions
Does Archify require a repository?
The README says no repository is required for a described system, but repository context and revision metadata improve verifiability when you are mapping real code.
Is the diagram itself proof that the architecture is correct?
No. Treat validation, source traces, and the preserved input revision as the evidence; the rendered diagram is the readable projection.
Sources
- Archify README (captured 2026-08-31)Source checked 2026-08-31
- Archify repositorySource checked 2026-08-31