Archify: An Open-Source Tool for AI-Generated Architecture Diagrams

In the age of AI-assisted programming, getting an AI agent to understand system architecture isn't particularly hard — but how do you turn lengthy text descriptions into intuitive visual diagrams? The open-source tool Archify offers a compelling answer: it enables AI agents to automatically generate, validate, and deliver interactive architecture diagrams, fundamentally changing how technical documentation gets made.

What Is Archify

Archify is an MIT-licensed open-source architecture diagram generation tool designed specifically for AI coding agents. Its core capability is reading system descriptions and helping coding agents produce interactive HTML diagrams, with built-in validation rules to ensure output quality.

Unlike traditional diagramming tools, Archify isn't a general-purpose editor — it's focused on translating an AI's understanding into standardized visual representations. It supports popular AI coding tools including Codex, Claude Code, Cursor, and OpenCode, and can be installed with minimal setup to give existing agents diagram generation capabilities.

Archify currently supports five diagram types, each tailored to specific use cases:

• Architecture Diagrams: Show core components and their relationships, ideal for depicting overall system structure
• Workflow Diagrams: Represent complete processes, decision nodes, and remediation paths
• Sequence Diagrams: Track interactions between participants in chronological order
• Data Flow Diagrams: Cover data transformations, storage, and consumption end-to-end
• Lifecycle Diagrams: Focus on state transitions, showing each phase from start to completion

Under the hood, Archify relies on Mermaid or a similar declarative diagram rendering engine, using JSON specifications as an intermediate layer to convert structured descriptions from AI output into SVG vector graphics. This "spec-first" design makes diagrams version-controllable — JSON files can be committed to a Git repository just like code, making it easy to track architectural evolution over time. Compared to manual drag-and-drop tools like Lucidchart or draw.io, Archify targets development teams that want to embed documentation generation into CI/CD pipelines or automation scripts. The MIT license means it's free to use in commercial projects, with the freedom to modify and redistribute.

The Intelligent Generation and Validation Mechanism

Archify's most elegant feature is its complete generate-validate-fix feedback loop. The entire process unfolds in three key phases:

Phase 1: Specification Generation

The agent first generates a JSON specification file, naming components and assigning unique identifiers, defining component relationships and rendering configuration. This spec file can be inspected at any time, committed to the project, and used for future maintenance.

Using the JSON spec as a "single source of truth for design intent" is a reflection of the modern Docs-as-Code philosophy. In this model, diagrams are no longer isolated static screenshots — they're structured data that can be read and modified programmatically. Each component has a unique identifier (typically a string ID), enabling the repair phase to pinpoint specific nodes rather than regenerating the entire diagram. This also means that during collaborative work, diff tools can clearly show which components were added, removed, or had their relationships changed between two versions, significantly reducing the communication overhead of architecture reviews.

Phase 2: Render Validation

After reading the spec, Archify performs rendering and runs up to 9 artifact checks, including:

• Valid SVG structure
• Geometric relationship correctness
• Crossing path handling
• Label and node spacing
• Legend layout integrity

If issues like label overlap or incorrect connections are detected, the system returns precise diagnostic feedback, clearly identifying the problem areas and pixel-level deviations.

Phase 3: Automatic Repair Loop

This is the most valuable part. When validation finds issues, the feedback is passed back to the coding agent, which modifies the specification and tries again. In real-world testing, an architecture diagram with overlapping tool-call labels and coordinator elements passed all checks after two targeted corrections; a workflow diagram whose label width exceeded the node (requiring 1002px but only 92px available) had the node automatically widened to 1032px with an adjusted layout.

Throughout the process, you can see not just the failed candidates, but also specific explanations and code change records, making the review process entirely transparent.

Real-World Performance and Limitations

Three independent tasks in a demonstration showcased Archify's practical capabilities:

Architecture Diagram Task: Building the architecture of an AI coding assistant, including components like user, coordinator, model, tool executor, and workspace — clearly showing how requests enter the system, how the model proposes actions, and how tool paths traverse the workspace.

Sequence Diagram Task: Simulating a product query flow involving a browser, catalog API, Redis, and Postgres. The diagram stepped through the complete call sequence for a cache miss, database query, and writing results back to cache, with clear ordering for every step.

Workflow Diagram Task: Breaking down Archify's own creation process across three swim lanes — requester, coding agent, and Archify tool — showing the full flow from requesting JSON authoring and validation to delivery, along with the decision logic for the repair branch.

One notable detail: artifact validation and browser testing are two separate steps. The initially generated sequence diagram passed build validation but overflowed across all four desktop sizes (a 1440×900 page reached an actual height of 1200px). Reducing message spacing and adjusting the diagram height ultimately made it fit all sizes.

Offline Capability Verification

The generated HTML viewer is highly portable. Testing showed that even after intercepting HTTP requests, diagrams still render correctly — search, theme switching, and SVG export all work offline without any console errors. This is particularly valuable for use in restricted network environments.

The HTML viewer can run offline because all dependencies — including rendering libraries, stylesheets, and interaction scripts — are inlined into a single HTML file at build time, with no need to load external resources from a CDN. This bundling strategy is conceptually similar to PWA offline caching, but simpler and more direct in implementation. For industries with strict network access controls — such as finance, healthcare, and government — or scenarios where you need to demo system architecture on-site without internet access, this feature has real practical value. The SVG export function further allows diagrams to be embedded in Word documents, Confluence pages, or PDF reports without relying on any online service.

Clear Limitations

Archify is not a universal solution. It has several key constraints:

1. No hosted sharing: The tool itself does not provide an online collaboration platform
2. Not a general-purpose editor: It's designed for parsing and standardization, not free-form drawing
3. Does not reflect real-time state: Diagrams represent design intent, not actual traffic in a production environment
4. Requires human review: If the agent fabricates dependency relationships, even the most polished rendering cannot guarantee factual correctness

For this reason, when working with a real repository, you must have the agent inspect the relevant files and explain the code basis for each relationship; if exploring a design concept, label it clearly as a draft.

The limitation that "diagrams show design intent rather than actual traffic" reveals a fundamental challenge with static architecture documentation: systems evolve over time, and documentation tends to lag behind. This is especially pronounced in microservice and cloud-native architectures. There are generally two approaches: one is to incorporate observability data from a service mesh (like Istio) to automatically generate "living documentation"; the other is to accept the limitations of static snapshots, as Archify does, and reduce the gap between documentation and reality by lowering the cost of updates (letting an AI agent regenerate with one command). Archify takes the latter approach — its value proposition is "cheap enough regeneration cost" rather than "automatically synchronized real-time state."

Cost and Usage Recommendations

Archify itself is MIT open-source, and the rendering tool requires no subscription fee, but your AI agent calls may still incur costs. Running multiple sub-agents increases API call expenses, so the recommended approach is:

Prioritize precise instructions: Rather than having multiple agents comb through everything at once, start with a clear, single task. One diagram is worth a thousand words — parallel work is only truly valuable when handling distinct problems like architecture and sequencing separately.

Recommended first prompt template:

Have Archify explain an API cache miss scenario involving a browser, API, Redis, and Postgres,
showing the response call sequence. Requirements:
1. Clearly state the topic and business logic
2. Use validation configuration profiles to ensure quality
3. Retain source files and attribution records
4. Generate a high-level architecture with 8–12 core components
5. Provide corresponding code justification

From there, iterate gradually: have the agent clarify relationships, fix overlapping labels, and explain error paths — keeping the modification process transparent and simplifying the review workflow.

Summary

Archify's value lies in translating an AI agent's abstract understanding into visual assets that can be reviewed, edited, and shared. It combines readable output, editable JSON source, and precise error feedback into a complete quality assurance mechanism.

While it cannot replace human review and isn't suited for every scenario, Archify is a productivity tool worth trying for teams that need to quickly generate technical documentation, demo system designs, or facilitate architecture discussions. It extends AI-assisted programming beyond code — into the realm of documentation and communication.