Reladraw: Ngôn ngữ sơ đồ nơi bạn tự quyết định vị trí từng thành phần

Nếu bạn từng vật lộn với việc vẽ sơ đồ kiến trúc hệ thống, hẳn bạn đã quen với hai thái cực khó chịu: hoặc là dùng Mermaid/Graphviz để máy tự sắp xếp (nhưng không kiểm soát được bố cục), hoặc là dùng Draw.io/Figma để kéo thả thủ công (nhưng tốn thời gian và cực kỳ khó để AI agent thao tác). Reladraw — một dự án mới vừa xuất hiện trên Hacker News — cố gắng dung hòa cả hai.

Sơ đồ kiến trúc được render từ file văn bản Reladraw

Vấn đề mà Reladraw muốn giải quyết

Các ngôn ngữ auto-layout như Mermaid, Graphviz hay D2 cho phép bạn khai báo các thực thể và mối liên kết, sau đó tự động sắp xếp mọi thứ. Đây là một siêu năng lực, và với phần lớn sơ đồ thì đó là lựa chọn đúng. Nhưng nó ngừng đúng ngay khi bạn có một hình dung cụ thể trong đầu và quan tâm đến việc thành phần nào nằm ở đâu.

Ở thái cực ngược lại là các công cụ định vị tuyệt đối như Draw.io, Excalidraw, Figma. Chúng cho bạn toàn quyền kiểm soát vị trí, nhưng đổi lại mỗi lần chỉnh sửa một sơ đồ phức tạp là một mớ thao tác thủ công chậm chạp. Với con người đã chậm, với AI agent còn tốn kém hơn nhiều — agent phải "dịch ngược" bức ảnh từ tọa độ ra ý nghĩa trước khi biết cần đổi con số nào.

Reladraw nhắm vào khoảng giữa. Mọi vị trí đều được phát biểu tương đối so với thứ khác, và không có bất kỳ tọa độ nào trong file:

node app "Web app"
node app.ui  "Interface"
node app.api "API"  below app.ui
node store "Database"  right of app  level with app
edge app.api -> store  "queries"  from: right  to: left

Không có cấu trúc lồng nhau, nên không dòng nào phụ thuộc vào vị trí hay thụt lề của dòng khác.

Sơ đồ được render từ ngôn ngữ Reladraw với bố cục xác định

Tại sao AI agent cần điều này

Trường hợp phổ biến không phải là vẽ một sơ đồ mới, mà là chỉnh sửa một sơ đồ đã có. Giả sử bạn yêu cầu: "chuyển dịch vụ auth sang trái và đặt một hàng đợi ra sau nó".

• Với tọa độ pixel, agent phải dựng lại bức tranh từ các con số trước khi tính được cần đổi con số nào.
• Với auto-layout, chẳng có gì để đọc cả — vì bố cục chưa bao giờ được viết ra. Agent chỉ có thể viết lại nguồn rồi render lại.
• Với vị trí được phát biểu, bố cục nằm ngay trong file dưới dạng câu văn. Muốn đổi bức tranh, chỉ cần đổi câu nói về vị trí của thứ đó.

Tác giả dự án đưa ra một quan sát tinh tế: "Ý định thì có thể xác nhận, còn kết quả thì không." Agent có thể đọc lại file của chính nó và thấy rằng database nằm dưới API, bốn máy đều treo vào sync hub. Nhưng nó không thể thấy rằng hai cluster neo vào hai thứ khác nhau giờ đã chồng lên nhau, hay một đoạn text tràn khỏi node — vì đó là kết quả được giải ra từ các câu lệnh, chứ không phải được phát biểu trực tiếp.

Cách hoạt động: giải hệ phương trình thay vì dò từng bước

Điểm thú vị về mặt kỹ thuật là Reladraw giải quyết bài toán bằng cách giải một hệ ràng buộc, chứ không phải "đi dọc theo chuỗi" như turtle graphics của PIC/pikchr.

Mỗi khoảng cách là một giá trị tối thiểu, không bao giờ là giá trị chính xác. Nếu bạn nói hai thứ nằm cạnh nhau, rồi nói thứ thứ ba nằm giữa chúng, thì hai thứ đầu bị đẩy ra đúng bằng khoảng mà thứ ba cần; xóa thứ ba đi, chúng lại khép lại. Không có con số nào bị "cũ" khi một đoạn text dài ra.

Trên mỗi trục, hệ thống có một tập khoảng cách tối thiểu, và bố cục chặt nhất thỏa mãn tất cả được tìm bằng longest paths — một đáp án duy nhất, không tìm kiếm, không thử-sai. Engine tính ra khoảng cách; còn thứ gì nằm ở phía nào của thứ gì là do file quyết định.

Minh họa khoảng cách tối thiểu trong bố cục Reladraw

"Tự do của engine được phép ảnh hưởng đến khoảng cách, và không bao giờ được ảnh hưởng đến quan hệ."

Đây là bài kiểm tra mà tác giả dùng để phân biệt Reladraw với auto-layout. Nếu một giá trị mặc định có thể đổi việc node nằm ở phía nào của node khác, thì ngôn ngữ đang thiếu một câu lệnh — và công cụ nên nói ra điều đó thay vì đoán bừa.

Sử dụng với AI agent

Reladraw quá mới để nằm trong dữ liệu huấn luyện của bất kỳ mô hình nào, nên agent phải được "dạy" ngôn ngữ này trước khi viết. Repo cung cấp sẵn một agent skill làm đúng việc đó — gồm cú pháp, khi nào nên dùng, và những gì việc đọc lại nguồn có thể/xác nhận được.

npx skills add reladraw/reladraw -g

Lệnh này cài đặt skill cho bất kỳ agent nào bạn dùng — Claude Code, Codex, Cursor, Copilot và các agent khác — mỗi cái vào thư mục skills riêng. Bỏ cờ -g để cài vào dự án hiện tại.

npm install -g reladraw
reladraw diagram.reladraw -o diagram.svg

Trạng thái hiện tại và những gì còn thiếu

Phiên bản 0.4.0 đã chạy được: parser, resolver và SVG renderer viết bằng TypeScript không có dependency runtime, cùng CLI nhận file văn bản và xuất ra SVG độc lập.

Những gì chưa có, xếp theo mức độ được nhớ đến:

• Báo cáo chẩn đoán: hiện công cụ chỉ render hoặc thất bại, chưa thể nói cho bạn biết sơ đồ vẽ thành công có chỗ nào sai.
• Định tuyến cạnh vòng qua node: một cạnh không nói gì về hướng đi sẽ là đường thẳng nối hai tâm — và nó sẽ cắt xuyên qua bất cứ thứ gì chắn đường.
• Thêm hình ảnh/icon: bộ icon và hình dạng hiện là tập đóng.
• Ngôn ngữ chưa ổn định — hãy kỳ vọng cú pháp sẽ còn thay đổi.

Điều đáng chú ý về triết lý thiết kế: một chẩn đoán không bao giờ tự sửa bố cục đã giải. Một công cụ kiểm tra mà được phép "nhích" node chính là một thuật toán auto-layout với chiến lược tìm kiếm tồi — sửa chỗ chồng này thành chỗ chồng khác mà không nhìn thấy toàn cục. Thay vào đó, Reladraw báo cáo vấn đề bằng đúng từ vựng của nguồn, và tác giả chỉnh sửa file văn bản.

So sánh với các dự án tiền nhiệm

Dự án	Điểm khác biệt
Archify	Thiết kế cho agent viết, nhưng định vị dùng grid hoặc tọa độ tự do — vẫn là vòng lặp emit, render, nhìn, chỉnh
PIC / pikchr	Có vị trí tường minh nhưng dùng turtle graphics — sơ đồ là chuỗi nét bút, không phải tập quan hệ giữa các thực thể có tên
Graphviz rank/cluster	Là ràng buộc trên engine auto-layout, không thay thế nó, nên kết quả vẫn mang tính "nổi lên"
Structurizr	Có layout thủ công thật, nhưng gắn chặt với mô hình C4

Reladraw được phát hành dưới giấy phép Apache-2.0 — tác giả giải thích rằng đây là một primitive tái sử dụng mà giá trị nằm ở mức độ được chấp nhận, nên hạn chế thương mại sẽ đi ngược mục đích. Giấy phép chỉ bao phủ phần code, không bao gồm tên gọi "reladraw" hay logo dự án.

Góc nhìn cho lập trình viên Việt Nam

Với các team đang xây dựng hệ thống tài liệu kiến trúc (architecture documentation) và ngày càng dựa vào AI agent để sinh/cập nhật tài liệu, Reladraw mở ra một hướng đáng theo dõi. Vấn đề muôn thuở của tài liệu là nó lỗi thời ngay khi viết xong — nếu agent có thể đọc một báo cáo chẩn đoán dạng văn bản và sửa đúng file nguồn, không cần render, không cần vision model, không cần số học pixel, thì chi phí duy trì tài liệu kiến trúc sẽ giảm đáng kể.

Dự án còn rất non và tác giả thừa nhận cú pháp sẽ thay đổi, nhưng ý tưởng cốt lõi — biến bố cục thành ngôn ngữ đọc được, thay vì để thuật toán quyết định — là một đóng góp đáng chú ý cho không gian công cụ sơ đồ vốn đã bão hòa.