Generating architecture diagrams with the Archify skill

Keeping architecture diagrams up to date has always been a lot of work. They are outdated the moment your diagram is saved.

Thanks to AI, keeping those diagrams up-to-date became a lot easier. I originally did this just by asking the AI to create and update mermaid diagrams, but recently I started experimenting with Archify.

You describe a system in plain words (or point your agent at a codebase), and you get back an interactive HTML diagram.

What is Archify?

Archify is an agent skill and some tooling around it. It works with Claude Code, Codex, Cursor, OpenCode and GitHub Copilot.

What makes it different, is that the agent doesn’t draw the diagram directly. It authors typed JSON that describes the system. Archify then renders that JSON and validates it. The output is a single, self-contained HTML file.

Installing the skill

For Claude Code:

npx -y skills@latest add https://archify.si --skill archify --agent claude-code --global --copy --yes

For GitHub Copilot:

npx -y skills@latest add https://archify.si --skill archify --agent github-copilot --global --copy --yes

For another agent, change the --agent value. The site has an agent-aware quick start that gives you the exact command.

If you only want to try it once, there is a no-install option:

npx skills use tt-a1i/archify@archify --agent codex

Using it

Then we can use it like any other skill. I adapted an example prompt from the Archify site to draw out the login flow for one of our applications:

Inspect this repository for evidence, then use Archify sequence mode to show the authentication flow from caller to final response. Include authentication, cache hit or miss, persistence fallback, return messages, and asynchronous trace or event emission. Keep message labels short and order unambiguous. Do not invent behavior that the code does not support.

You can give it different kinds of input:

A description of a system or process in plain words
A repository, so the diagram is derived from the code
Existing Mermaid diagram

Remark: With Mermaid, the skill doesn’t convert the syntax mechanically. The agent reads the diagram for topology and meaning, then authors fresh Archify JSON.

Missing facts should be marked or clarified, so expect the agent to ask follow-up questions. Once you have a first version you can refine it in chat.

Tip: If you don't know where to start, you can explain your use case on the Archify website. It will recommend a recipe and a possible diagram to use:

Which diagram types does it support?

Archify supports ten diagram types. You don’t have to pick one. You ask the question you have, and Archify picks the picture that answers it.

Systems and flows

Architecture: what is it made of? Services, databases and security boundaries, and how they connect.
Workflow: what happens next? Steps across people or stages, lane by lane. Think approval chains or a CI/CD pipeline.
Sequence: who says what, in what order? An API call chain with its returns, for example.
Data flow: where does it all go? Data moving through a pipeline, or documents through review.
Lifecycle: where does it stand now? States and the transitions between them, including waits, retries and endings.

Structure and time

Entity-relationship: how does the data relate? Tables with full column lists, keys, and crow’s-foot cardinality.
Class / interface: which types fulfil which contracts? Inheritance, implementation, composition and dependencies.
Tree: how is it organised? A repository’s modules, a platform or a team, level by level.
Timeline: what happened, and when? Events on a real time axis. An incident or a release history fits well.
Waterfall: where did the time go? Nested spans on one clock, so the slow step and the parallel work stand out.

Nice to know is that you are not limited to software alone. The site shows a leave plan, a job search and a monthly budget, generated and validated exactly like a system diagram.

Validation before delivery

This is what makes Archify different from my previous “ask the LLM for a Mermaid diagram” approach. Archify runs a number of checks before you get your file:

validate: checks the schema, IDs and references, and the layout itself (crossings, label clearance, legend room). A blank chart cell is an error, not a zero.
deliver: renders to a staging copy and swaps it in atomically. A failed render never replaces your existing file.
check: reads the delivered HTML back and checks it again. The receipt records hashes of the source and the file.
browser-check: opens the file in Chrome at several desktop sizes and checks overflow, text readability and controls.

Remark: Validation checks the structure of the diagram, not the truth of your claims. If the agent draws a service that doesn’t exist, Archify will happily render it. We still have to review the content ourself.

Exporting and sharing

The result is one HTML file with no server and no runtime, so you can attach it to an email or a PR comment. Some features I like to mention:

Dark and light themes in one file (press T to toggle)
Export to PNG, JPEG, WebP, SVG and WebM, or straight to the clipboard
Interactive exploration: find a node, trace and play a route, focus on one component

One-page answers

Archify can also answer a question as a page instead of a map. The conclusion comes first, followed by one panel per question with tables, steps, code, charts and validated diagrams. Claims cite numbered sources and repository code is pinned to a commit.

Use Archify to answer as one page: Describe the login and logout flows for this repository.

My conclusion

I tried it on a few different use cases and the results look promising. The diagrams are not only visually attractive but the interactivity makes them a great tool to better understand what is going on.

It's ultimate promise is that Archify should make less mistakes when creating diagrams. Does it keep that promise?

So far, yes. But I would recommend to make your own conclusion and give it a try.

More information

Cache stampede: when our cache turned against us

While investigating some performance issues, we ran into an ASP.NET Core API that cached a fairly expensive aggregation query for 60 seconds. Under normal load, that was fine: one request rebuilds the cache, everyone else reads from it. Under peak load, dozens of requests would arrive in that same expiry window, all see a cache miss, and all fire the same expensive query in parallel. The database didn't like that. That was the moment when our caching layer stopped helping and started hurting. A burst of requests comes in at the same time, all miss the cache, and all go hammer the database or the downstream API at once. That's a cache stampede . The cache was supposed to protect our backend, and for a few hundred milliseconds it did the opposite. Why this happens IMemoryCache.GetOrCreate (and its async sibling) looks like it protects you, but it doesn't add any locking on its own. Look at the naive version: public async Task<Report> GetReportAsync(string key) ...

The art of simplicity

Search This Blog