Mermaid: vẽ sơ đồ luồng dữ liệu bằng chữ, để bản bàn giao không lỗi thời sau sprint đầu tiên

Hai tuần trước buổi bàn giao, bạn mở design doc và thấy sơ đồ kiến trúc vẫn là ảnh chụp từ buổi workshop đầu tiên. Trong ảnh còn một hàng đợi đã bị bỏ và một API mà khách hàng đã đổi tên. File gốc nằm trong máy của một người đã rời dự án, nên không ai sửa được.

Chính những người làm Mermaid đã viết thẳng vấn đề này vào repo chính thức: vẽ sơ đồ và viết tài liệu ngốn thời gian quý giá của developer, rồi lại nhanh chóng trở nên lỗi thời.

Knut Sveidqvist, một kiến trúc sư phần mềm người Thụy Điển, tạo ra Mermaid năm 2014 với mục đích làm việc viết tài liệu dễ hơn. Phần lõi đến nay vẫn là mã nguồn mở theo giấy phép MIT.

Với một FDE, đây là chuyện thường ngày. Bạn đi vào hệ thống của khách, nối dữ liệu, dựng agent hay pipeline, rồi rời đi. Nhóm kỹ thuật của khách phải tự vận hành phần còn lại, và họ chỉ hiểu được những gì có trong tài liệu bàn giao.

Vì sao sơ đồ dạng chữ lại sống lâu hơn?

Mermaid đọc những đoạn mô tả văn bản viết theo lối Markdown rồi dựng thành sơ đồ: sửa chữ là sơ đồ đổi theo. Không có file ảnh hay file thiết kế nào phải giữ riêng. Sơ đồ chỉ là vài dòng chữ trong cùng repo với code.

GitHub hiển thị sơ đồ Mermaid trong issue, Discussions, pull request, wiki và file Markdown, tức là đúng những nơi chứa design doc và README bàn giao. Khi đồng nghiệp đổi một bước xử lý, họ sửa luôn dòng mô tả trong cùng pull request, và người review thấy cả hai thay đổi trong cùng một diff.

Một luồng dữ liệu, sáu dòng chữ

Thử hình dung bạn triển khai một trợ lý trả lời câu hỏi cho bộ phận vận hành của một công ty logistics. Dữ liệu được xuất từ ERP mỗi đêm, đưa vào kho lưu trữ, qua một job ingestion để cập nhật vector store, và cuối cùng agent đọc từ đó.

Trong GitHub, bạn đặt sơ đồ vào một code block có nhãn ngôn ngữ mermaid:

flowchart LR
    ERP[Customer ERP] -->|nightly export| S3[(Object storage)]
    S3 --> ING[Ingestion job]
    ING --> VS[(Vector store)]
    VS --> AG[Ops agent]
    AG --> UI[Ops team chat]

Flowchart gồm hai thành phần: node là các hình khối, edge là mũi tên hoặc đường nối. Dòng đầu tiên quyết định hướng của sơ đồ. LR nghĩa là vẽ từ trái sang phải, hợp với luồng dữ liệu vì người đọc theo dõi được nguồn ở bên trái và đầu ra ở bên phải.

Chi tiết đáng giá nhất là nhãn trên mũi tên, như “nightly export” ở trên. Người nhận bàn giao cần biết dữ liệu chảy qua đâu, và họ cũng cần biết nó chảy khi nào. Hãy ghi tần suất, định dạng hay tên job lên edge, để đội vận hành của khách không phải đi tìm bạn hỏi lại sau khi bạn đã rời dự án.

Lỗi hay gặp: một dấu gạch đứng bị thiếu

Giả sử trước buổi bàn giao bạn sửa vội dòng đầu và làm mất dấu gạch đứng đóng nhãn:

ERP[Customer ERP] -->|nightly export S3[(Object storage)]

Nhãn của edge phải nằm gọn giữa hai dấu gạch đứng. Bản đúng chỉ cần thêm lại đúng một ký tự:

ERP[Customer ERP] -->|nightly export| S3[(Object storage)]

Đừng để người nhận bàn giao là người đầu tiên phát hiện ra. Dán đoạn mô tả vào Mermaid Live Editor, công cụ mà GitLab giới thiệu để học Mermaid và gỡ lỗi sơ đồ. Nếu sơ đồ không dựng lên được, so từng dòng với phiên bản chạy được gần nhất, thường lỗi nằm ở chính dòng bạn vừa sửa.

Lỗi thứ hai khó thấy hơn vì sơ đồ vẫn hiển thị bình thường: node chỉ có tên viết tắt như ING mà không có chữ trong ngoặc. Mã node là để bạn viết cho nhanh, còn phần chữ trong ngoặc mới là thứ đội của khách đọc. Một sơ đồ toàn chữ viết tắt nội bộ cũng khó hiểu như một ảnh chụp đã cũ.

Giới hạn: phiên bản và tính năng beta

Mermaid có một loại sơ đồ riêng là architecture, có từ phiên bản v11.1.0, dùng để thể hiện quan hệ giữa các service và tài nguyên trong các deployment trên cloud hay CI/CD. Nghe thì rất hợp với tài liệu bàn giao. Nhưng tài liệu chính thức ghi rõ loại sơ đồ này vẫn đang ở giai đoạn beta, nên cú pháp có thể thay đổi.

Rủi ro thứ hai là nền tảng nào hiển thị sơ đồ. GitHub khuyên bạn kiểm tra phiên bản Mermaid nó đang dùng để chắc cú pháp của mình được hỗ trợ, bằng cách đặt lệnh info vào một khối mermaid. GitLab cũng hiển thị Mermaid trong Markdown và công bố hỗ trợ Mermaid phiên bản 12.

Nếu khách hàng dùng một nền tảng khác với nền tảng bạn dùng để viết, một sơ đồ dùng tính năng mới có nguy cơ không hiển thị như bạn thấy trên máy mình. Vì thế tài liệu bàn giao nên dùng flowchart. Chỉ dùng architecture khi bạn đã kiểm tra nó hiển thị đúng trên đúng repo của khách.

Học gì trước, và đưa vào CV ra sao

Bắt đầu với flowchart: node, edge, nhãn trên mũi tên và hướng LR. Như vậy đã đủ vẽ phần lớn luồng dữ liệu bạn gặp ở khách hàng. Tập thói quen chạy mọi thay đổi qua Live Editor trước khi commit, giống như chạy test trước khi đẩy code.

Về nghề nghiệp, tài liệu bàn giao là thứ nhà tuyển dụng ít khi thấy nhưng FDE nào cũng phải viết. Một repo portfolio có README kèm sơ đồ luồng dữ liệu được cập nhật qua nhiều commit cho thấy bạn đã nghĩ đến người sẽ vận hành hệ thống sau khi bạn rời đi. Khi phỏng vấn, hãy mở chính sơ đồ đó và giải thích từng edge.

Lần tới khi thấy mục “Architecture” trong design doc chỉ có một ảnh chụp màn hình, đừng vẽ lại bằng công cụ kéo thả. Hãy viết sáu dòng chữ và commit chúng cùng với code.