Archify Architecture Diagram Skill Tutorial: Installation, Repository Analysis, Validation, and Troubleshooting

Archify is a Agent Skill for Codex CLI, Claude Code, Cursor, OpenCode, and Raven. It converts a system description or code repository into an interactive technical diagram, rather than simply fitting a piece of text into a general flowchart template.

The generated results use the typed JSON IR as the source of fact, and deliver the self-contained HTML after verification; the browser can also export PNG, SVG, WebM and 1200×630 sharing cards. It is suitable for architecture review, README diagrams, failure path descriptions, and comparison before and after changes, but it cannot replace the review of source code, deployment configuration, and operation logs.

Project address: tt-a1i/archify

First determine whether Archify is suitable for the current task

Archify offers five main chart types:

Don’t cram all the information into one Architecture diagram. The cache rollback of login requests is suitable for Sequence; the approval and rollback of CI is suitable for Workflow; the order status transition is more suitable for Lifecycle.

Archify Nor is it a Mermaid theme, online hosting platform, or WYSIWYG editor. Officially, automatic parsing of Mermaid, general automatic layout, hosted sharing and WYSIWYG editing are clearly outside the current scope.

Check Node.js and working directory before installation

The install command is run via npx, so first check Node.js and npm:

1
2
3

node --version
npm --version
npx --version

If the command does not exist, install the currently supported Node.js LTS first and then reopen the terminal. Do not attribute installation failures to Codex or Claude Code when npx is missing.

Also confirm which repository should be analyzed:

1
2

git rev-parse --show-toplevel
git status --short

Workspaces with uncommitted changes can still be analyzed, but the source code evidence in the diagram must correspond to an explicit commit. For formal review, first record:

1

git rev-parse HEAD

Install the Archify Skill globally

The official quick installation command is:

1

npx skills add tt-a1i/archify -g

-g means global installation. The common Skill locations of each Agent are different:

The installer will process the directory according to the target Agent. It is not recommended to manually copy the same Skill to multiple unknown locations. After the installation is complete, restart the Agent and ensure that the new session rescans Skills.

If you just want to try it temporarily in Codex, you can execute:

1

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

A temporary trial is suitable for evaluating the result. For reproducible team use, standardize the installation method and record the Archify repository version or commit in the project documentation.

Verify that the agent actually calls Archify

Don’t judge availability just by “installed successfully”. After creating a new session, give a clearly defined request:

1
2
3

分析当前仓库，然后使用 archify 生成一张高层运行时架构图。
只保留 8–12 个核心组件，标出一条主请求路径、外部依赖和信任边界。
把补充说明放进卡片，不要继续增加连线。

Three things to check during acceptance:

1. The Agent explicitly selects and calls Archify instead of generating Mermaid code impersonation results.
2. The output contains HTML, which can be opened separately, and the corresponding typed source data.
3. Every component, relationship, and boundary in the diagram can be traced to the repository or input description, with no unsupported services added.

If the Agent only returns an explanation, first let it explain whether the Skill has been found, and then check the installation directory and new session status.

Generate the first architecture diagram from the repository

High-quality results depend on scope. You can use the following prompt words:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

Use archify to map this repository's runtime architecture.

Scope:
- entry points and long-running processes
- API, worker, database, cache and external services
- one primary request path
- authentication and trust boundaries

Constraints:
- 8–12 main nodes
- do not infer services that are not present in source or configuration
- place evidence and secondary details in cards
- deliver the validated HTML and typed source together

For a monorepo, the directory should be qualified first:

1
2

只分析 apps/api、packages/auth 和 packages/database。
忽略 examples、generated、vendor 和构建产物。

If the scope is not limited, the Agent may draw tests, scripts, and historical implementations as production components, resulting in too many nodes and unclear meanings of edges.

Choose Sequence or Data Flow for a specific request path

Cache fallback fits into the timing diagram:

1
2
3
4

Use archify to draw this login sequence:
Browser -> Web App -> API -> JWT validation -> Redis session lookup.
When Redis misses, query PostgreSQL and repopulate Redis.
Show failure returns and timeout boundaries, but keep the happy path primary.

When it comes to privacy and data handling, use Data Flow instead:

1
2
3

画出用户上传文件后的数据流。
标出上传入口、病毒扫描、对象存储、元数据数据库、异步处理器和下载消费者。
明确包含个人信息的节点、跨边界传输和保留期限，不推测未提供的加密方式。

The difference is: Sequence focuses on the calling sequence; Data Flow focuses on data movement, transformation, storage and sensitive boundaries.

Keep JSON IR, don’t just deliver screenshots

Archify Drive rendering using typed JSON IR. Teams should also save:

• original JSON;
• Verified HTML;
• SVG or PNG for documents;
• The corresponding Git commit when generated;
• Manual review of records.

Leaving just PNG loses repeatable editing and validation capabilities. HTML is suitable for interactive viewing, SVG is suitable for document and version management, PNG is suitable for platforms that do not support SVG.

Example of suggested directory:

1
2
3
4
5

docs/architecture/
├── runtime.architecture.json
├── runtime.architecture.html
├── runtime.architecture.svg
└── README.md

Document scope and commits in README.md:

1
2
3
4

Source revision: 4f2c1ab
Scope: apps/api, packages/auth, packages/database
Excluded: tests, generated, vendor
Review status: manually checked

Use the repository CLI to validate and deliver

To call the validator in the Archify repository directly, first clone the project and enter its directory:

1
2
3

git clone https://github.com/tt-a1i/archify.git
cd archify
node bin/archify.mjs doctor

You can check out the built-in examples first:

1
2

node bin/archify.mjs demo /tmp/archify-demo
node bin/archify.mjs guide "Show CI/CD checks, approval, deploy, and rollback"

Verify a Workflow JSON:

1
2
3
4

node bin/archify.mjs validate workflow \
  examples/agent-tool-call.workflow.json \
  --quality showcase \
  --json

Generate one-time deliverable HTML:

1
2
3
4
5
6

node bin/archify.mjs deliver workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase \
  --open \
  --json

On failure, read diagnostics[], rule code, concrete object, and supportedFixes, and only modify the pointed problem. Don’t let the agent rewrite the entire graph just because one validation failure occurs.

Security boundaries for local preview

You can use preview when you need to change while viewing:

1
2
3
4

node bin/archify.mjs preview workflow \
  examples/agent-tool-call.workflow.json \
  /tmp/workflow.html \
  --quality showcase

The official preview mode only binds the random port of 127.0.0.1 and only listens to the specified JSON file. When a candidate file fails verification, the browser continues to display the previous qualifying result.

Do not change the preview service to 0.0.0.0 for remote access. Deliver self-contained HTML when sharing is required, or publish static export files in a controlled documentation system.

Use Architecture Delta to review changes

A design or PR review can compare two validated snapshots:

1
2
3
4
5

node archify/bin/archify.mjs compare architecture \
  base.json \
  head.json \
  architecture-delta.html \
  --json

The results display Before, Delta, and After, distinguishing between facts that have been added, deleted, modified, moved, or rerouted. It compares two written and validated structures and does not automatically determine risk, scope, or whether they can be combined.

Therefore, manual answers are still needed:

• Whether the changes come from real code and configuration;
• Whether the trust boundary changes;
• Whether data storage or external dependencies are newly added;
• Whether the deployment sequence and rollback need to be adjusted;
• Test whether the new path is covered.

How to validate a generated diagram

Check the facts first, then the visuals:

Fact Check

• Whether the entry is consistent with the real startup command;
• Whether the service relationship can be found in code, configuration or documentation;
• Whether to distinguish between synchronous calls and asynchronous messages;
• Databases, caches, and queues are not mixed into the same storage;
• Trust boundaries and external systems are not left out;
• There are no “common components” that the Agent can add on its own in the picture.

Visual inspection

• Main paths can be identified within seconds;
• Nodes do not block each other;
• The connection line does not pass through the label;
• Secondary information does not overwhelm primary relationships;
• Readable in both dark and light themes;
• The exported expressions of SVG, PNG are consistent with HTML.

Deliverability check

• HTML can be opened in a disconnected environment;
• JSON and HTML use the same version;
• The file name is stable and does not contain temporary random names;
• The diagram does not contain keys, intranet addresses or customer data;
• Git Commit and build scopes are documented.

Common troubleshooting

The agent cannot find Archify

Reconfirm installation and session:

1

npx skills add tt-a1i/archify -g

Then exit completely and restart Codex or Claude Code. If there are multiple Skill directories at the same time, check which one the Agent actually reads, and do not continue to repeat the installation.

Mermaid is generated instead of Archify HTML

Explicitly write “use archify” in the prompt and require delivery of validated HTML and typed source. If it is still not called, it means that the Skill has not been discovered or is covered by other rules.

The diagram contains too many components

Narrow requests to a single runtime path, limit 8–12 master nodes, and move logs, metrics, tests, and helper scripts to description cards.

The structure of the diagram is inconsistent with the source code

First record the Git commit and analysis directory, then remove every node that lacks supporting evidence. Do not fill gaps in the actual repository with assumptions such as “there is usually a Redis instance.”

Verification failed but the old image is still displayed

This is the last-good preview mechanism. Check diagnostics[] to correct the current candidate; do not misjudge that the old image is still visible as the new version has been successfully verified.

SVG renders incorrectly on a documentation platform

First open SVG directly in the browser to check the font, external resources and cropping range. Use PNG when the display cannot be stable, but continue to retain the SVG and JSON source files.

A reusable acceptance checklist

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[ ] 已记录 Archify 安装方式和版本
[ ] 已记录仓库 Git 提交与分析范围
[ ] 图表类型与问题匹配
[ ] 主路径、外部依赖和信任边界明确
[ ] JSON IR 与 HTML 同时保存
[ ] validate 或 deliver 返回成功
[ ] 图中每个关键关系都有输入或源码依据
[ ] 深色与浅色主题可读
[ ] SVG/PNG 导出可打开
[ ] 不包含密钥、内网地址或客户数据
[ ] 人工评审没有把图当作运行时事实证明

Summary

The value of Archify is not “automatic drawing in one sentence”, but organizing technical descriptions into typed, verifiable, and interactive deliverables. A reliable process should be: limit the scope, select the correct image type, generate JSON IR, pass verification, manually check the facts, and then deliver HTML and static export.

In particular, keep the Git commit and analysis scope for code repositories. Diagrams can help teams discuss architecture, but source code, configuration, testing and operational data are still the ultimate basis.