Archify Generates Verifiable System Architecture Diagrams

Background and Context

As AI-assisted coding tools become standard in developer workflows, the ability to have an agent both understand and render a system's internal structure has grown increasingly valuable. Yet a long-standing pain point emerges when developers ask agents to draw architecture, sequence, or data-flow diagrams: the models frequently generate images probabilistically, fabricating components, connections, or routes that never existed. Such diagrams look professional but cannot be verified, and once they enter code review or cross-team communication they risk misdirecting decisions. Archify (tt-a1i/archify) is a Node.js rendering and validation system built to address exactly this gap.

Positioned at the intersection of the "architecture-as-code" movement and the coding-agent toolchain, Archify embeds itself as an agent skill into Cursor, Claude Code, Codex CLI, and OpenCode. It converts a codebase or a plain system description into an interactive, verifiable system map. Written primarily in JavaScript, the project is tagged under agent-skills, architecture-diagram, codex, and coding-agents, and currently sits at the development build v2.17.0-dev.1. Its accumulating attention on GitHub reflects genuine community interest in the niche of verifiable architecture diagrams.

Deep Analysis

Archify's core design decouples drawing from validation. It requires the agent to first emit a typed JSON intermediate representation, which the system then deterministically compiles into HTML or SVG. The graphics are no longer a free product of the model's sampling but the constrained result of type and deterministic checks. This yields four perceptible capabilities. First, "open and show": five diagram types, four presets, dark and light themes, branding, and restrained animation make diagrams suitable for both chat windows and formal presentations.

Second, "review architecture changes before merge": the system compares two validated snapshots in a Before / Delta / After format, precisely reporting additions, removals, changes, moves, and reroutes, making architectural evolution auditable. Third, "every interaction grounded in fact": node search, optional opening of revised and verified source, upstream/downstream reachability tracing, semantic-role comparison, and guided story playback all operate without inventing topology. Fourth, "trust and share in one file": the typed IR and deterministic checks produce a self-contained HTML file, exportable to PNG, SVG, WebM, and a 1200x630 share card.

Onboarding is deliberately frictionless. Installation requires a single command, npx skills add tt-a1i/archify -g, and Cursor users can open an agent-oriented quickstart for precise global and project-level commands. No repository needs to be cloned; developers simply describe a system in any agent chat to generate a diagram, embedding the drawing action seamlessly into existing conversational workflows. Documentation offers three entry points, including a Proof Lab with eleven checked-in scenarios, each accompanied by its JSON source, named views, and validation receipts.

Industry Impact

Archify's broader significance lies in importing the engineering principle of verifiability into diagramming, historically the least controllable环节 of AI output. For developer communities it offers a paradigm for treating agent output as an auditable artifact; for engineering teams, pre-merge architecture-change comparison and reachability tracing directly serve code review and risk control. The project demonstrates real-world grounding by tracing an architecture map generated from the actual repository mco-org/mco at a specific commit, paired with reachability tracing and typed source.

The tool also carries risks worth watching. When a diagram's credibility depends heavily on the type constraints and validation rules of the IR, those rules may contain gaps, or the agent may deviate from fact during IR generation, reducing validation to a formality. Moreover, deterministic compilation removes randomness but cannot guarantee that the topology description matches the real code exactly; critical paths still require manual verification. The layered experience lets developers choose depth according to trust needs, from quick sketches in chat to reviewable, shareable deliverables.

Outlook

Directions worth observing include whether validation receipts will become standard credentials within team workflows, whether semantic-role comparison and guided storytelling will further reduce cross-team communication costs, and whether the tool will be natively adopted by more types of coding agents and CI pipelines. Archify represents a pragmatic path: it does not pursue more ornate AI drawings but ones that can be trusted. As the architecture-as-code ecosystem matures, its determinism-based approach may set a benchmark for how agent-generated diagrams are validated, audited, and shared across engineering organizations.

Ultimately, the project reframes diagrams from disposable images into verifiable artifacts. Whether that shift gains traction will depend on whether teams come to treat validation receipts as authoritative and whether the deterministic compilation model proves robust enough to replace manual topology checks in production code review.