Archify là gì? Hướng dẫn cài đặt và tạo sơ đồ kiến trúc bằng AI

Tóm tắt nhanh:

Archify là một Agent Skill mã nguồn mở giúp biến mô tả hệ thống, codebase hoặc luồng xử lý thành các sơ đồ kỹ thuật có thể tương tác ngay trong Cursor, Claude Code, Codex CLI và OpenCode. Thay vì chỉ sinh ảnh tĩnh, Archify tạo specification dạng typed JSON, kiểm tra tính hợp lệ rồi biên dịch thành một file HTML/SVG tự chứa, có tìm kiếm, focus node, truy vết đường đi, dark/light theme và export sang nhiều định dạng.

Archify phù hợp nhất khi bạn muốn AI hỗ trợ tạo architecture diagram, workflow, sequence diagram, data-flow diagram hoặc lifecycle diagram nhưng vẫn cần đầu ra có cấu trúc và khả năng kiểm chứng. Cách nhanh nhất để bắt đầu là chạy npx skills add tt-a1i/archify -g, sau đó yêu cầu coding agent sử dụng Archify để mô tả hệ thống hoặc phân tích repository hiện tại.

Archify là một hệ thống render và validation viết trên Node.js dành cho các AI coding agent. Agent không trực tiếp “vẽ” một ảnh tùy ý; thay vào đó, nó tạo một typed JSON intermediate representation (JSON IR), sau đó Archify dùng renderer và validator để chuyển specification đó thành HTML/SVG theo cách xác định và có thể kiểm tra lại. Package hiện yêu cầu Node.js 18 trở lên và được phát hành theo giấy phép MIT.

Archify hỗ trợ năm nhóm sơ đồ chính: Architecture, Workflow, Sequence, Data Flow và Lifecycle. Output có thể là một file HTML tự chứa, đồng thời Viewer hỗ trợ export PNG, JPEG, WebP, SVG và WebM. Các sơ đồ còn có khả năng chuyển dark/light theme, tìm kiếm component, zoom, focus, truy vết upstream/downstream và kiểm tra một route cụ thể.

Tại thời điểm bài viết được cập nhật, GitHub Releases đánh dấu v2.16.0 là bản stable mới nhất, trong khi nhánh phát triển chính đã mang version v2.17.0-dev.1. Vì dự án phát triển khá nhanh, khi triển khai cho team bạn nên kiểm tra release stable thay vì mặc định lấy trạng thái của main.

Vì sao Archify đáng chú ý?

Điểm khác biệt lớn của Archify là nó không chỉ tập trung vào việc làm sơ đồ “đẹp”. Workflow của dự án được thiết kế theo hướng generate → validate → deliver → iterate. Specification được kiểm tra schema, layout và artifact trước khi output cuối được ghi nhận là hợp lệ. Khi validation thất bại, CLI có thể trả về diagnostic có cấu trúc thay vì chỉ đưa ra một lỗi Node.js khó xử lý.

Điều này đặc biệt hữu ích khi dùng AI. Với công cụ vẽ tự do, model có thể tạo ra diagram trông hợp lý nhưng không nhất quán với source. Archify hướng agent về một cấu trúc dữ liệu có schema, đồng thời có chế độ lấy evidence từ repository khi người dùng yêu cầu sơ đồ phản ánh code thực tế. Các interaction như route tracing cũng dựa trên relationship đã được author trong specification, thay vì tự suy diễn thêm topology trong Viewer.

Archify cũng không phải một web app cần dựng server hay một dịch vụ Docker riêng. Artifact HTML được thiết kế để tự chứa và có thể mở trực tiếp trong trình duyệt. Điều đó khiến nó phù hợp với documentation, technical design review, pull request, onboarding developer và các buổi trình bày kiến trúc.

Cách cài đặt Archify

Trước tiên, hãy đảm bảo máy có Node.js 18+. Renderer của Archify khai báo engine node >=18. Bạn không cần chạy npm install bên trong Skill chỉ để sử dụng renderer; tài liệu của dự án mô tả package runtime theo hướng zero-dependency.

Cách đơn giản nhất là cài Skill toàn cục:

npx skills add tt-a1i/archify -g

Lệnh này là quick start chính thức được Archify khuyến nghị. Skill có thể được dùng với Cursor, Codex, Claude Code và OpenCode.

Ví dụ, để cài rõ ràng cho Cursor ở chế độ global và non-interactive:

npx -y skills add tt-a1i/archify \
  --skill archify \
  --agent cursor \
  --global \
  --copy \
  --yes

Bạn có thể thay cursor bằng agent được hỗ trợ như codex, claude-code hoặc opencode. Ngoài global install, Archify cũng hỗ trợ cài riêng cho repository hiện tại bằng cách bỏ --global.

Chưa muốn cài vĩnh viễn? Có thể thử với Codex bằng:

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

Với cài đặt thủ công, Claude Code có thể đọc Skill từ ~/.claude/skills/, Codex từ ~/.agents/skills/, còn OpenCode hỗ trợ các vị trí như ~/.config/opencode/skills/. Raven sử dụng phương án giải nén archify.zip vào ~/.raven/workspace/skills.

Cách sử dụng Archify từ prompt đến HTML

Điểm thuận tiện nhất là không bắt buộc phải có repository. Bạn có thể bắt đầu chỉ bằng một câu mô tả:

Use Archify to draw:

Browser -> API -> Redis cache -> PostgreSQL fallback.
Show the main request path and make cache miss explicit.

Archify sẽ chọn cấu trúc phù hợp, tạo JSON IR, validate và render diagram. Khi đang làm việc trong codebase thật, hãy yêu cầu agent phân tích repository trước:

Analyze this repository, then use Archify to create
a high-level runtime architecture diagram.

Show 8-12 core components, the primary request path,
external dependencies and trust boundaries.

Đây cũng là pattern được tài liệu chính thức đề xuất cho source-backed architecture diagram.

Sau khi có phiên bản đầu tiên, bạn không cần viết lại toàn bộ prompt. Có thể tiếp tục bằng các yêu cầu nhỏ như:

Add Redis between API and PostgreSQL.
Move authentication before the API.
Highlight the rollback path.
Reduce secondary components and keep one clear primary path.

Archify giữ specification có cấu trúc nên agent có thể chỉnh sửa từng phần thay vì phải tạo lại sơ đồ từ đầu.

Nếu làm việc trực tiếp với source của Archify, CLI còn cung cấp các lệnh kiểm tra hữu ích:

cd archify

node bin/archify.mjs doctor

node bin/archify.mjs guide \
  "Show an API request with Redis cache miss"

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

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

validate dùng để kiểm tra candidate; deliver là bước acceptance cuối cùng trước khi tạo artifact; còn preview có thể mở một loopback-only local preview trong quá trình chỉnh sửa.

Chọn đúng loại sơ đồ trong Archify

Để có kết quả tốt, hãy nói rõ mục đích thay vì chỉ yêu cầu “vẽ architecture”. Archify có năm renderer với vai trò khác nhau.

Ví dụ, “Browser gọi API, API kiểm tra Redis rồi fallback PostgreSQL” phù hợp với Sequence nếu bạn muốn nhấn mạnh thứ tự request, nhưng có thể dùng Architecture nếu mục tiêu là giải thích các component của toàn hệ thống. Khi chưa chắc chắn, Archify có lệnh guide để gợi ý loại diagram theo scenario.

Mẹo sử dụng hiệu quả và những giới hạn cần biết

Prompt tốt cho Archify nên cung cấp scope, component quan trọng, primary path, external dependency và boundary. Với diagram dùng để trình bày, ít node nhưng rõ quan hệ thường hiệu quả hơn việc nhồi toàn bộ class, queue và endpoint vào một màn hình. Skill contract của dự án cũng khuyến nghị bắt đầu bằng một main path rõ ràng và giới hạn khoảng 12 primary nodes cho một artifact thông thường.

Một điểm cần hiểu đúng là Archify không phải WYSIWYG diagram editor, không phải Mermaid theme và hiện cũng không nhắm tới hosted sharing. Mermaid có thể được dùng làm input ngữ nghĩa cho một số dạng flowchart, sequence hoặc state diagram, nhưng Archify sẽ chuyển topology sang JSON riêng thay vì chỉ “skin” lại Mermaid.

Ngoài ra, Archify có cơ chế kiểm tra bản cập nhật để hiển thị thông báo về stable release; cơ chế này không tự tải hay tự cài update. Với môi trường cần chặn network hoàn toàn, tài liệu cho phép đặt ARCHIFY_UPDATE_CHECK_DISABLED=1.

Archify đáng thử khi bạn đã dùng Cursor, Claude Code, Codex hoặc OpenCode và muốn biến AI từ công cụ “mô tả kiến trúc bằng chữ” thành một workflow tạo technical diagram có cấu trúc, validation và artifact có thể chia sẻ. Điểm mạnh nhất của dự án nằm ở sự kết hợp giữa natural-language authoring, typed JSON IR, deterministic validation và interactive HTML output.

Với người mới, workflow hợp lý nhất chỉ gồm ba bước: cài Skill bằng npx skills add tt-a1i/archify -g, mở codebase hoặc mô tả hệ thống bằng text, sau đó yêu cầu agent “use Archify” để tạo diagram. Khi cần tìm hiểu thêm các demo và tính năng Viewer, có thể xem homepage chính thức của Archify.