Mermaid: Tạo sơ đồ kiến trúc hệ thống với Mermaid Architecture Diagram - Part 3

Mermaid Architecture

Trong quá trình làm tài liệu kỹ thuật, việc trình bày kiến trúc hệ thống rõ ràng và dễ hiểu là rất quan trọng. Thay vì dùng PowerPoint hay vẽ tay bằng draw.io, Mermaid Architecture Diagram mang lại một cách viết sơ đồ bằng cú pháp text thuần — gọn gàng, version control tốt, dễ chỉnh sửa và tích hợp vào Markdown.

Mermaid giờ đây hỗ trợ vẽ sơ đồ kiến trúc hệ thống (architecture diagram) với các thành phần như API, database, storage, và icon sinh động từ Iconify.

Sơ đồ kiến trúc

%%{ init: { "theme": "base" } }%% architecture-beta group frontend(cloud)[Frontend App] service web(server)[Web Client] in frontend group backend(cloud)[Backend Service] service api(cloud)[API Gateway] in backend service db(database)[PostgreSQL] in backend web:R -- L:api api:B -- T:db

Note: Mình chỉ giải thích 1 số thành phần trong diagram

architecture-beta: khai báo một sơ đồ kiến trúc sử dụng cú pháp architecture-beta của Mermaid

group frontend(cloud)[Frontend App]:hai báo một nhóm có tên định danh là frontend. Tên định danh này sẽ được dùng để tham chiếu đến nhóm sau này.

(cloud): hiển thị nhóm này dưới dạng một hình đám mây

[Frontend App]: Đây là nhãn (label) sẽ hiển thị trên biểu đồ cho nhóm chứa Web Client.

Junction

junctions là điểm nối (junction point) cho phép liên kết nhiều luồng vào một điểm trung gian – giúp sơ đồ gọn hơn và rõ ràng hơn, nhất là khi nhiều dịch vụ cần kết nối chung tới một node.

Syntax

junction {junction id} (in {parent id})?

Ví dụ

%%{ init: { "theme": "base" } }%%
architecture-beta
    service frontend(cloud)[Frontend]
    service api(cloud)[API]
    service auth(cloud)[Auth Service]
    service db(database)[PostgreSQL]

    junction j1

    frontend:R -- L:j1
    api:T -- B:j1
    auth:L -- R:j1
    j1:B -- T:db

%%{ init: { "theme": "base" } }%% architecture-beta service frontend(cloud)[Frontend] service api(cloud)[API] service auth(cloud)[Auth Service] service db(database)[PostgreSQL] junction j1 frontend:R -- L:j1 api:T -- B:j1 auth:L -- R:j1 j1:B -- T:db

Kết quả

Frontend   API   Auth
     \     |     /
       \   |   /
         (Junction)
             |
            DB

Giải thích

[source]:[source_anchor] -- [target_anchor]:[target]

• frontend: tên node nguồn
• R: (Right) – vị trí bắt đầu của mũi tên từ node nguồn
• L: (Left) – vị trí kết thúc của mũi tên ở node đích
• j1: node đích (ở đây là junction)

VD: frontend (→ Right side) ------- (← Left side) j1

Ký hiệu	Ý nghĩa	Vị trí trên node	Ví dụ	Giải thích
T	Top	Trên cùng (phía trên node)	nodeA:B -- T:nodeB	Mũi tên đi từ dưới nodeA lên trên nodeB
B	Bottom	Dưới cùng (phía dưới node)	nodeA:T -- B:nodeB	Mũi tên đi từ trên nodeA xuống dưới nodeB
L	Left	Bên trái node	nodeA:R -- L:nodeB	Mũi tên đi từ phải nodeA sang trái nodeB
R	Right	Bên phải node	nodeA:L -- R:nodeB	Mũi tên đi từ trái nodeA sang phải nodeB

Iconify là gì?

Iconify là một thư viện mã nguồn mở chuyên cung cấp icon dạng SVG. Nó tập hợp hơn 200,000+ icon từ nhiều bộ icon nổi tiếng như:

• logos (AWS, Azure, Google Cloud, GitHub…)
• mdi (Material Design Icons)
• twemoji, simple-icons, fontawesome,...

Danh sách icon: https://icon-sets.iconify.design/ 

Tích hợp Iconify vào mermaid

Thêm đoạn script này vào cuối document

 <script type="module">
	import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
	mermaid.initialize({ startOnLoad: true });

	mermaid.registerIconPacks([
		{
		  name: 'logos',
		  loader: () =>
			fetch('https://unpkg.com/@iconify-json/logos@1/icons.json').then((res) => res.json()),
		},
	]);

</script>

Ví dụ

  architecture-beta
      group api(logos:aws-lambda)[API Layer]
      service db(logos:aws-aurora)[Aurora DB] in api
      service disk1(logos:aws-glacier)[Cold Storage] in api
      service disk2(logos:aws-s3)[S3 Storage] in api
      service server(logos:aws-ec2)[EC2 Worker] in api

      db:L -- R:server
      disk1:T -- B:server
      disk2:T -- B:db

architecture-beta group api(logos:aws-lambda)[API Layer] service db(logos:aws-aurora)[Aurora DB] in api service disk1(logos:aws-glacier)[Cold Storage] in api service disk2(logos:aws-s3)[S3 Storage] in api service server(logos:aws-ec2)[EC2 Worker] in api db:L -- R:server disk1:T -- B:server disk2:T -- B:db

Trên đây là cách tích hợp Mermaid Architecture Diagram với Iconify để trực quan hóa kiến trúc hệ thống bằng cú pháp đơn giản. Hy vọng bài viết giúp bạn dễ dàng hơn trong việc trình bày và ghi chú kỹ thuật.