Archify: Turn Any Codebase into an Interactive, Verifiable System Map in Chat

1. 🌟 The Architecture Documentation Dilemma in AI Coding

In modern software development, AI coding agents (such as Cursor, Claude Code, Codex CLI, and OpenCode) can generate hundreds of lines of code in seconds. However, as codebases expand rapidly, human engineers face a severe bottleneck: comprehending overall runtime architecture and verifying structural changes before merging.

Traditional diagramming approaches suffer from two fatal flaws:

Static and Brittle: Handcrafted PlantUML or Mermaid diagrams drift out of sync with actual code within days.
Hallucinated Topologies: Asking LLMs to draw diagrams directly often produces imaginary nodes, mislabeled components, and fictitious network flows.

Archify (github.com/tt-a1i/archify) bridges this gap. Operating as a standardized Agent Skill, Archify combines a strictly typed JSON Intermediate Representation (IR) with a deterministic Node.js compiler to produce interactive, verifiable system maps directly from chat.

flowchart LR
    subgraph Input ["Agent Code Inspection"]
        Agent["🤖 AI Agent (Cursor / Claude / Codex / OpenCode)"]
        Source["📦 Git Repo Source Files"]
    end

    subgraph Compiler ["Archify Deterministic Pipeline"]
        JSON["📐 Typed JSON IR Schema"]
        Engine["⚡ Archify Node.js Validator & Layout Engine"]
    end

    subgraph Output ["Interactive Artifacts"]
        HTML["🌐 Self-Contained Interactive HTML"]
        ShareCard["🖼️ 1200x630 OpenGraph Share Cards"]
        Diffs["🔄 Before / Delta / After Architecture PR Diffs"]
    end

    Agent -->|Reads AST| Source
    Agent -->|Emits Schema| JSON
    JSON --> Engine
    Engine --> HTML & ShareCard & Diffs

2. 📐 Architecture: Typed JSON IR & Deterministic Compilation

Rather than letting models draw loose SVG strings, Archify enforces a decoupled, two-stage pipeline:

Stage 1 (Reasoning & Extraction): The LLM analyzes the repository and outputs a strongly typed JSON specification containing verified nodes, services, protocols, ports, and directed edges.
Stage 2 (Deterministic Compilation): Archify’s Node.js compiler validates the JSON against schema invariants, calculates layout geometry, and renders zero-hallucination interactive web artifacts.

🛡️ Zero Hallucination Guarantee:

If an agent attempts to link an unverified node or invent a non-existent database layer, Archify’s deterministic compiler rejects the IR before rendering, ensuring every box and arrow corresponds to real source files.

3. 📊 5 Diagram Types & 4 Presentation Presets

Archify supports five core visualization modes tailored for software engineering:

Diagram Type	Best Used For	Interactive Feature
🏗️ Architecture Map	Full-system component topology and boundaries	Semantic role lenses (e.g. backend vs. cache vs. database)
⚡ Signal / Workflow	Event-driven queues and agentic tool dispatching	Guided story step-by-step chapter playback
⏱️ Sequence Diagram	Cache-miss fallback loops and API authentication flows	Shortest directed path inspection between services
🌊 Data Flow	ETL pipelines and streaming data transformations	Volume, throughput, and protocol annotations
🔄 Lifecycle Map	Entity state machines and container orchestrations	State transition invariants and error fallback routes

4 Polished Visual Presets:

Signal Flow: High-contrast modern dark mode with animated telemetry pulses.
Blueprint: Technical engineering drafting style with grid coordinates.
Classic: Clean, documentation-ready light theme for technical specifications.
Neon / Tactical: Vibrant dark mode optimized for executive demos and presentations.

4. 🔄 Review Architecture Diffs Before Merge (Before / Delta / After)

One of Archify’s standout features for engineering teams is visual pull request architecture diffs:

Snapshot Mode	Scope & Architectural Meaning	Visual Diff Indication
🔵 Before	Snapshot of current `main` branch architecture	Baseline reference
🟢 Delta	Exact added, removed, changed & rerouted components	Green highlights, strike-throughs & dashed paths
🟣 After	Target post-merge architectural state	Final verified blueprint

When reviewing a PR that refactors a caching layer or migrates a message queue, the agent outputs two validated snapshots. Archify visually highlights:

Added nodes (e.g., new Redis cluster) in green.
Deprecated services in red strike-through.
Rerouted RPC calls with animated dashed arrows.

5. 🔍 Grounded Interactive Exploration

Every generated Archify diagram is a living, interactive application contained in a single portable HTML file:

Shortest Route Probing: Click any two components (e.g., Web Client and PostgreSQL) to highlight the exact authored route, active middleware, and latency expectations.
Reach Analysis (Upstream / Downstream): Select a microservice to instantly spotlight every upstream dependent and downstream dependency.
Guided Story Playback: Walk stakeholders through a complex user registration or checkout flow one chapter at a time with built-in slide controls.
Share Card Export: One-click export to 1200×630 PNG share cards for pull request descriptions, documentation, or release announcements.

6. 🚀 Quickstart: Installing Archify

Archify installs globally as a standard Agent Skill:

# Global installation for all supported agents
npx skills add tt-a1i/archify -g

# Non-interactive Cursor installation
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

Asking Your Agent:

Once installed, trigger Archify inside your agent session:

Use archify to map this repository's runtime architecture and highlight the database access flow.

7. 💡 4 Takeaways for Modern Engineers

Separation of Reasoning from Rendering: Letting LLMs output typed data structures (JSON IR) while delegating visual layout to deterministic compilers eliminates visual hallucinations.
Architecture as Code: Maintaining system maps as validated JSON in git ensures architectural documentation evolves in lockstep with production code.
Interactive Diffs Streamline Code Reviews: Reviewing architectural delta maps alongside git diffs prevents unintended coupling and hidden architectural regressions.
Self-Contained Artifacts Win: Single-file HTML diagrams that require zero external servers or cloud dependencies offer maximum portability and enterprise compliance.

1. 🌟 Nghịch Lý Tài Liệu Kiến Trúc Trong Thời Đại AI Coding

Trong kỷ nguyên phát triển phần mềm hiện đại, các tác tử AI coding (như Cursor, Claude Code, Codex CLI, hay OpenCode) có thể viết hàng trăm dòng code chỉ trong vài giây. Tuy nhiên, khi mã nguồn phình to nhanh chóng, các kỹ sư phần mềm phải đối mặt với một nút thắt cổ chai lớn: nắm bắt bức tranh toàn cảnh kiến trúc hệ thống và kiểm chứng các thay đổi cấu trúc trước khi merge.

Các phương pháp vẽ sơ đồ truyền thống luôn gặp phải 2 điểm nghẽn nghiêm trọng:

Tĩnh và Nhanh Lỗi Thời: Các sơ đồ PlantUML hoặc Mermaid vẽ thủ công thường bị lệch pha với mã nguồn thực tế chỉ sau vài ngày.
Ảo Giác Cấu Trúc (Hallucination): Khi yêu cầu các mô hình LLM tự do vẽ sơ đồ, chúng thường tự bịa ra các node không có thật trong code và nối dây sai luồng dữ liệu.

Archify (github.com/tt-a1i/archify) ra đời như một giải pháp chuẩn mực. Hoạt động dưới dạng một Agent Skill tiêu chuẩn, Archify kết hợp cấu trúc dữ liệu trung gian JSON IR định kiểu nghiêm ngặt với trình biên dịch Node.js xác định để tạo ra các bản đồ hệ thống tương tác và kiểm chứng được ngay trong khung chat.

flowchart LR
    subgraph DauVao ["Rà Soát Mã Nguồn"]
        Agent["🤖 AI Agent (Cursor / Claude / Codex / OpenCode)"]
        Source["📦 File Mã Nguồn Dự Án"]
    end

    subgraph TrinhBienDich ["Quy Trình Biên Dịch Archify"]
        JSON["📐 Cấu Trúc Typed JSON IR"]
        Engine["⚡ Trình Kiểm Tra & Dựng Layout Node.js"]
    end

    subgraph KetQua ["Tài Sản Xuất Bản"]
        HTML["🌐 File HTML Tương Tác Độc Lập"]
        ShareCard["🖼️ Ảnh Bìa Share Card 1200x630"]
        Diffs["🔄 So Sánh Diff Kiến Trúc PR (Before/After)"]
    end

    Agent -->|Đọc cây AST| Source
    Agent -->|Xuất JSON chuẩn| JSON
    JSON --> Engine
    Engine --> HTML & ShareCard & Diffs

2. 📐 Kiến Trúc: JSON IR Định Kiểu & Biên Dịch Xác Định

Thay vì để mô hình AI vẽ các chuỗi SVG tự do không kiểm soát, Archify phân tách quy trình thành 2 giai đoạn độc lập:

Giai đoạn 1 (Suy luận & Bóc tách): LLM rà soát mã nguồn dự án và xuất ra một file JSON đặc tả chặt chẽ chứa các node thành phần, service, giao thức truyền thông, cổng port và các kết nối có hướng.
Giai đoạn 2 (Biên dịch xác định): Trình biên dịch Node.js của Archify kiểm tra tính hợp lệ của JSON theo schema, tính toán tọa độ layout và render ra trang web tương tác với tỷ lệ chính xác 100%.

🛡️ Cam kết Không Ảo Giác (Zero Hallucination):

Nếu AI agent cố tình nối vào một service không tồn tại trong source code hoặc bịa ra tầng database ảo, trình biên dịch Archify sẽ tự động từ chối bản ghi IR trước khi render, đảm bảo mọi khối hộp và mũi tên đều phản ánh đúng thực tế mã nguồn.

3. 📊 5 Loại Sơ Đồ & 4 Giao Diện Trình Chiếu Chuẩn Mực

Archify hỗ trợ 5 chế độ trực quan hóa chuyên sâu cho kỹ thuật phần mềm:

Loại Sơ Đồ	Ứng Dụng Điển Hình	Tính Năng Tương Tác
🏗️ Bản Đồ Kiến Trúc (Architecture)	Cấu trúc tổng thể các thành phần và ranh giới hệ thống	Lăng kính phân vai trò (Backend vs Cache vs Database)
⚡ Luồng Tín Hiệu (Workflow)	Hàng đợi sự kiện và luồng điều phối công cụ agent	Trình phát theo từng chương hướng dẫn (Guided Story)
⏱️ Sơ Đồ Trình Tự (Sequence)	Quy trình xử lý lỗi cache-miss và luồng xác thực OAuth	Dò tìm tuyến đường ngắn nhất giữa các dịch vụ
🌊 Luồng Dữ Liệu (Data Flow)	Pipeline xử lý ETL và luồng dữ liệu thời gian thực	Chú thích băng thông, lưu lượng và giao thức mạng
🔄 Vòng Đời Trạng Thái (Lifecycle)	Máy trạng thái entity và quản lý vòng đời container	Rà soát các bất biến trạng thái và nhánh xử lý lỗi

4 Giao diện hiển thị chuyên nghiệp:

Signal Flow: Chế độ Dark mode hiện đại với hiệu ứng xung nhịp dữ liệu chuyển động.
Blueprint: Phong cách bản vẽ kỹ thuật kiến trúc với lưới tọa độ chuẩn xác.
Classic: Giao diện Light mode thanh lịch, tối ưu cho tài liệu kỹ thuật văn bản.
Neon / Tactical: Giao diện tương phản cao dành cho các buổi demo và thuyết trình dự án.

4. 🔄 So Sánh Diff Kiến Trúc PR Trước Khi Merge (Before / Delta / After)

Một tính năng cực kỳ giá trị cho các đội ngũ kỹ sư là so sánh trực quan sự thay đổi kiến trúc trong Pull Request:

Chế Độ Snapshot	Phạm Vi & Ý Nghĩa Kiến Trúc	Quy Chuẩn Đánh Dấu Trực Quan
🔵 Before	Kiến trúc hiện tại trên nhánh `main`	Bản đồ tham chiếu gốc
🟢 Delta	Chi tiết các node thêm, xóa, sửa và đổi luồng	Viền xanh node mới, gạch đỏ node xóa, nét đứt đổi luồng
🟣 After	Kiến trúc đích sau khi merge Pull Request	Bản thiết kế hoàn chỉnh sau cùng

Khi review một PR tái cấu trúc tầng cache hoặc thay đổi hệ thống message queue, agent xuất ra 2 bản snapshot. Archify sẽ đánh dấu trực quan:

Thành phần mới bổ sung (ví dụ: cụm Redis mới) bằng màu xanh lá.
Thành phần bị loại bỏ bằng màu đỏ gạch ngang.
Các luồng gọi RPC bị đổi hướng bằng mũi tên nét đứt chuyển động.

5. 🔍 Trải Nghiệm Tương Tác Sâu & Kiểm Chứng Mã Nguồn

Mỗi sơ đồ Archify sinh ra là một ứng dụng tương tác hoàn chỉnh gói gọn trong một file HTML duy nhất:

Dò tìm tuyến đường (Route Probing): Bấm chọn 2 thành phần bất kỳ (ví dụ: Web Client và PostgreSQL) để làm sáng toàn bộ tuyến đường kết nối, các middleware đi qua và độ trễ ước tính.
Phân tích tầm ảnh hưởng (Upstream / Downstream): Chọn một microservice để ngay lập tức làm nổi bật các dịch vụ đang phụ thuộc vào nó và các dịch vụ nó gọi tới.
Trình chiếu theo kịch bản (Guided Story): Dẫn dắt người xem qua từng bước của quy trình đăng ký hoặc thanh toán phức tạp như một slide thuyết trình động.
Xuất ảnh Share Card 1200×630: Xuất nhanh ảnh chuẩn OpenGraph chất lượng cao để đính kèm vào mô tả Pull Request, tài liệu README hoặc bài viết kỹ thuật.

6. 🚀 Hướng Dẫn Cài Đặt & Sử Dụng Nhanh

Cài đặt Archify toàn cục dưới dạng Agent Skill cho các trợ lý AI:

# Cài đặt toàn cục cho tất cả các tác tử AI được hỗ trợ
npx skills add tt-a1i/archify -g

# Hoặc cài đặt trực tiếp cho Cursor
npx -y skills add tt-a1i/archify --skill archify --agent cursor --global --copy --yes

Ra lệnh cho Agent:

Sau khi cài đặt, chỉ cần yêu cầu agent trong khung chat:

Sử dụng archify để vẽ bản đồ kiến trúc runtime của repository này và làm nổi bật luồng truy cập database.

7. 💡 4 Bài Học Kiến Trúc Cho Kỹ Sư Hiện Đại

Tách Biệt Suy Luận Khỏi Dựng Hình: Để LLM sinh dữ liệu có cấu trúc (JSON IR) và ủy quyền việc vẽ layout cho trình biên dịch giúp triệt tiêu hoàn toàn lỗi ảo giác sơ đồ.
Kiến Trúc Dưới Dạng Mã Nguồn (Architecture as Code): Quản lý tài liệu kiến trúc dưới dạng file JSON trong Git giúp tài liệu luôn đồng bộ với mã nguồn thực tế.
Diff Trực Quan Giúp Tăng Tốc Review PR: Đánh giá bản đồ sai khác kiến trúc song song với git diff giúp ngăn chặn các phụ thuộc vòng hoặc hồi quy thiết kế tiềm ẩn.
Tài Sản Độc Lập Mang Lại Tính Bền Vững: File HTML tự thân không phụ thuộc server bên ngoài đảm bảo tính bảo mật và dễ dàng lưu trữ lâu dài trong nội bộ doanh nghiệp.