Archify: AI Skill That Reads Code to Generate Interactive Architecture Diagrams

Taking over an unfamiliar codebase consumes the most time not in writing code but in understanding its overall structure: which module does what, where requests enter, where data ends up. Documentation is usually missing or outdated, forcing developers to piece it together manually.

Recently I discovered archify on GitHub (13k+ stars), an open-source Agent Skill that installs into AI coding tools such as Cursor, Claude Code, Codex CLI, and OpenCode. Once installed, a single prompt like "map the runtime architecture of this repository" makes the AI read the actual code and produce an interactive HTML architecture diagram — no manual description required. As the README states, these diagrams are extracted from the real repository, not hallucinated from prompts.

What archify does

1. Reads the codebase directly, no lengthy descriptions needed

Most AI diagramming tools require you to describe the system in text first; the quality of the diagram depends entirely on how well you describe it — which means you must already understand the architecture. archify bypasses this: it navigates the repository itself, discovers entry points, routing, module dependencies, and assembles the diagram. The only input needed is a one-sentence instruction.

For example, when run against the public repository mco-org/mco, archify generated a runtime architecture diagram that matches the actual code structure.

Runtime architecture diagram generated from mco-org/mco

2. Diagram nodes link back to source code

Because the diagram is derived from code, each node carries an SRC marker. Clicking it jumps to the exact file and line number, pinned to a specific Git commit so the reference never drifts. This turns the diagram into a verifiable document rather than a speculative sketch. When explaining a module's logic to a colleague, you simply click the marker instead of searching the codebase live.

3. Five diagram types for different perspectives

Architecture diagram: components, services, databases, cloud resources, security boundaries — the overall system structure.

Workflow: swimlane flowcharts suited for CI/CD pipelines, approval flows, exception branches — anything with sequential steps.

Sequence diagram: API call chains, cache fallback, authentication checks — who calls whom, in what order, and what returns.

Data flow diagram: where data originates, how it is transformed, where it is stored, with sensitive-data boundaries highlighted.

Lifecycle diagram: state machines, retries, waits, terminal states — e.g., an order from creation to completion.

Workflow example

Sequence example

4. Interactive diagrams, not static images

The output HTML includes a full viewer: press / to search nodes, click a component to see its upstream and downstream dependencies, press R to trace the complete path between two nodes step by step. It can also play a guided story — like a slide deck that walks through the system chapter by chapter. Press F for presentation mode, which auto-fits the screen. All interactions are grounded in actual nodes and edges; the tool never invents non-existent call relationships.

Guided story

Path exploration

5. Consistent output quality, not luck

Earlier approaches asked the model to emit SVG or Mermaid directly, yielding unpredictable results. archify separates concerns: the model only produces a structured JSON describing nodes and edges; a dedicated renderer handles layout and drawing, followed by an automated validation pass. Invalid diagrams (e.g., label-edge collisions) are rejected with specific error messages and suggested fixes. In practice this raises the quality floor significantly — diagrams are reliably usable every time.

6. Serious export and sharing features

Light and dark themes, one-click toggle.

PNG exported at 4× resolution, crisp for slides or print.

SVG embeds both light and dark styles in a single file; on GitHub README it automatically follows the viewer's system theme.

WebM animated diagrams and 1200×630 social-sharing cards for release notes or posts.

Dark theme

Light theme

7. Architecture diffing for change reviews

When refactoring, you can compare before/after diagrams to generate three views: Before, Delta, After. Added components, removed components, and changed connections are listed line by line. This makes architecture reviews far clearer than verbal descriptions.

Architecture diff

Getting started in one command

npx skills add tt-a1i/archify -g

The installer prompts for your AI tool; select accordingly. For a one-off trial without permanent installation:

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

After installation, open your project and simply say: "Use archify to map the runtime architecture of this repository." Iterative tweaks are just as easy — e.g., "Add a Redis instance," "Move the auth module to the left," "Highlight the rollback path." Only the mentioned parts are updated; the rest of the diagram stays intact.

My take

archify picks the right battle: architecture diagrams drift from code the moment they are drawn from memory. By letting AI read the code and anchoring every node to a verifiable source location, the diagram becomes a living, auditable document.

The division of labor is also well executed: AI handles understanding and information structuring (what it's good at), while deterministic code handles layout, rendering, and validation (where stability matters). This separation lifts the quality floor well above raw model-generated SVG.

It's not a diagram editor — no drag-and-drop, no Mermaid conversion. It does one thing: turn a codebase into a presentable, verifiable architecture diagram. If you're onboarding a new project or frequently explaining system structure, it's worth a try — just one command away.

Open source

https://github.com/tt-a1i/archify