Used for: assessing a tool for explaining AI-assisted codebases while preparing this publication workflow. Tested: source review of Archify v2.16.0, 2026-09-01.

Verdict: use when a team needs a reproducible technical map that an AI coding agent can refine and a human can inspect. Avoid it when the job is freehand sketching or a general-purpose diagram editor.

Quick verdict

• Best for: architecture reviews, onboarding maps, workflow explanations, and before/after diagram comparisons.
• Avoid if: the requirement is WYSIWYG drawing, automatic Mermaid parsing, or hosted collaborative diagram editing.
• Cost: Archify is MIT licensed. Running it still requires a compatible coding-agent environment and Node.js where its renderer runs.
• Main limitation: validation can check the supplied diagram structure and rendering rules; it cannot prove that an agent’s model of a real system is complete or operationally correct.

AI-assisted coding makes it cheap to add routes, workers, integrations, and data stores. It does not make the resulting system easy to explain. The usual answer is a diagram, but screenshots drift, manual edits are difficult to review, and a polished drawing can still overstate what a codebase does.

Archify is built around a narrower job: turn a codebase analysis or system description into an inspectable technical artifact. An agent produces typed JSON intermediate representation (IR); Archify validates it and deterministically compiles it to self-contained HTML and SVG. The result can be opened locally, shared as one file, and exported in common formats.

What I used it for

This was a research-only evaluation, not a claim that Archify has been run against every system in this publication. The practical question was narrower: what should a developer use when a growing project needs a system map that is more durable than a whiteboard screenshot?

That question appears early in small products. A project may begin with a page and an API. Then it accumulates authentication, queues, caches, background work, analytics, and third-party services. The code can remain understandable file by file while the overall path becomes hard to describe. The same issue shows up in applied builds: a public project such as the Olist Ecommerce Analytics Agent is easier to evaluate when its roles, data boundary, and query constraints can be presented as a concrete system map rather than a long paragraph.

Archify supports five diagram types, each aimed at a different question:

1. Architecture diagrams for components, services, storage, boundaries, and a primary path.
2. Workflow diagrams for ordered steps, approvals, branches, exceptions, and runbooks.
3. Sequence diagrams for calls and returns over time, such as an authentication check or cache fallback.
4. Data-flow diagrams for sources, transforms, stores, consumers, and sensitivity boundaries.
5. Lifecycle diagrams for states, retries, waits, cancellation, and terminal outcomes.

Choosing a type matters. An architecture map should not pretend to explain timing. A sequence should not attempt to carry every infrastructure detail. A lifecycle should make waits and terminal states legible instead of hiding them behind generic arrows.

Setup or workflow

The repository documents the skill installation command:

npx skills add tt-a1i/archify -g

Archify documents workflows for Cursor, Claude Code, Codex CLI, and OpenCode. A useful first prompt is deliberately scoped: ask for the core components, one primary path, external dependencies, and trust boundaries. Resist the urge to ask for every class and service at once. A map with too many edges is not more truthful; it is only harder to read.

For an unfamiliar repository, a bounded request can look like this:

Analyze this repository, then use Archify to create a high-level runtime architecture diagram.
Show 8–12 core components, one primary path, external dependencies, and trust boundaries.
Put supporting detail in cards instead of adding more edges.

The agent then creates typed JSON IR. Archify’s documented process validates schema, layout, HTML/SVG rendering, routes, and label-to-route clearance before a showcase-quality artifact replaces a prior verified output. This is the useful boundary: an agent can propose the interpretation, while the renderer applies repeatable checks to the artifact it delivers.

After that, refinement should stay specific. Add one dependency. Move one component. Highlight one rollback path. A controlled change is easier to review than regenerating the entire diagram from a vague request.

What worked in the documented design

Archify’s strongest idea is not a visual preset. It is the separation between meaning and rendering. Typed IR provides a source that can be inspected and revised; deterministic compilation produces a consistent artifact from that source; validation keeps layout and route constraints inside the delivery loop.

The resulting HTML supports more than a static view. The documented viewer can search nodes, trace authored routes, inspect upstream or downstream reach, compare semantic roles, and play guided stories. Those interactions only reuse authored nodes and relationships. That constraint is important: a technical viewer should not invent topology while a reader is trying to understand a real system.

Architecture Delta is another useful example of restraint. Given validated Before, Delta, and After snapshots, it reports authored additions, removals, changes, moves, and reroutes. It does not claim performance impact, security improvement, merge safety, or runtime risk unless evidence outside the diagram supports those conclusions. For code review, that distinction is healthier than treating a changed diagram as proof that a change is safe.

The export surface is practical: Archify documents self-contained HTML plus PNG, SVG, WebM, and 1200×630 share cards. That suits an architecture review, a README, a release note, or a team handoff without requiring a separate hosted diagram product.

What broke or costs more than expected

A validated diagram is not a verified system. The renderer can reject malformed source, confusing routes, and visual collisions. It cannot know whether the agent missed a hidden queue, misunderstood a permissions boundary, or inferred behavior from an incomplete repository scan. Treat the diagram as a communication artifact that deserves code review, not as runtime monitoring or a substitute for tests.

There is also an intentional scope boundary. Archify is not a general drawing editor, a Mermaid theme, automatic Mermaid parsing, hosted sharing, or a WYSIWYG canvas. That is not a defect when the need is repeatable technical communication. It is a poor fit when a workshop needs people to sketch freely and negotiate the model live.

The same rule applies to source evidence. Archify can link evidence-backed nodes to revision-verified public source when that mode is requested. Ordinary diagrams may remain source-free. Readers should ask which kind of map they are viewing before treating it as a source-level audit.

Alternatives and trade-offs

Mermaid is the lower-friction option when plain-text diagrams inside documentation are enough. A design canvas is better when manual composition and collaborative sketching are the main jobs. A slide can be better when the audience needs a short, curated narrative rather than an explorable map.

Archify fits between those choices. It is for teams that already work through coding agents and want a diagram source, renderer, validator, and viewer in the same workflow. It brings more structure than a hand-drawn diagram and more visual interaction than a text-only diagram definition. That structure costs prompt discipline and a review step.

Tips to reuse

1. Start with one question per map: system structure, one workflow, one request path, one data journey, or one lifecycle.
2. Keep the first architecture map to 8–12 core components. Put nuance in cards instead of crossing every possible edge.
3. Ask the agent to state unknowns. Missing information is better than invented topology.
4. Generate a Before snapshot before a structural change and an After snapshot afterward. Use Delta to explain the authored difference, not to claim operational impact.
5. Review the artifact alongside source and tests. A map helps people reason; it does not replace evidence.

For broader context on using AI tools in real project work, see this publication’s project notes and public build records.

Sources and related reading

• Archify repository and README
• Archify project page
• Archify scenario guide
• Archify Proof Lab