Mermaidでアーキテクチャ図が書けるようになったらしい

株式会社Schooの[@hiroto_0411](https://x.com/hiroto_0411)です！
新卒研修でMermaidを使って以来、簡単な図はMermaidで書くようになりました！推しツールの1つになってきています🫶
そんなMermaidでアーキテクチャ図(Architecture Diagrams)を書けるようになったと聞いたので、実際に試してみました！

## Mermaidとは
https://mermaid.js.org/

シーケンス図、クラス図、状態遷移図などをテキストベースで作ることができるツールです。

### Mermaidを書くときに使うと便利なツール
**Mermaid Live Editor**
(2024/09/12現在、Mermaid v11.1.0以上に対応していないためアーキテクチャ図は見られないです)

ブラウザでMermaid記法を試すことができます。

<img width="500" alt="mermaid" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/30bc6830-1900-cee3-2539-ba63a62957e1.png">

https://mermaid.live/edit#pako:eNpt0E1qwzAQBeCrTGYb-wJeJBRaaApddavNID1bAv20ikQJIXevLNe7aDVivifQu7NOBjzxFT8VUePVyZIlqEjtvHinMZ5Ox49k40Tv8D7ROg9k0y9JBt1SPT_FG9MSV0IWkingn667sdGxZ9rDbksPdOmJrlvs8JxfaAY8LRlSDjxwQA7iTPvFfQ0oLhYBiqc2GsxSfVGs4qNRqSV93aLmqeSKgXOqi-VpFn9tt_ptpOwV7ATGlZQ_t5p6Wzt865vNPf4ACDBrdw

**Markdown Preview Mermaid Support(VSCode拡張機能)**
マークダウンで記述しながらプレビューを見られます。
<img width="500" alt="mermaid" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/45a2d370-a421-7080-885a-2904d4da0177.png">

**GitHub**
<img width="400" alt="github-example" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/065aa92c-4b32-d002-011b-09a64990292f.png">

[サンプル](https://github.com/hiroto1220/mermaid-sample/blob/main/architecture-diagrams/sample.md)
2024/09/12現在、GitHubではデフォルトのアイコンは使えますがiconifyのアイコンは使えないみたいです。

**draw.io**
(2024/09/12現在、アーキテクチャ図は対応していないです。)

Mermaidのコードからdraw.ioで図を作成することができます。draw.ioを使うことで、どうしても人が修正したい箇所の微調整を行うことができます。

draw.ioの上のタブの配置→挿入→高度な設定→Mermaid
の流れで選択して、表示されるテキストエリアにMermaidのコードを入力します。
<img width="400" alt="drawio" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/f09e3882-2de6-b99c-60ac-cd690aefd05d.png">

<img width="400" alt="drawio" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/6b288070-ab84-08cc-9ddd-2155683b4cec.png">

<img width="400" alt="drawio" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/b6342aa3-ba19-4075-7a79-32e4fb1fa2da.png">

<img width="400" alt="drawio" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/c78b6769-094c-afa1-d2d7-224f07fc5bb9.png">

### Mermaidの良いところ
- デザインや配置を自分で考える必要がない
- 図を書き換えるのが比較的楽
    - テキストを書き換えるだけで変更できるので、矢印1つ1つを動かしたりしなくて良い
    - 複雑な図になってくると微調整は必要
- version管理できる
- 生成AIに書いてもらうこともできる
- Notionやdraw.io、GitHubなどさまざまなサービスでテキストから図を作成・挿入することができる


## アーキテクチャ図とは
システムやアプリケーションの構成要素とその相互関係、動作の流れを視覚的に表現した図のことです。

**参考**

https://aws.amazon.com/jp/what-is/architecture-diagramming/


## Mermaidでアーキテクチャ図を書いてみよう！

https://mermaid.js.org/syntax/architecture

ドキュメントを参考にして、実際に触ってみました！

**今回試した環境**
VSCode
Markdown Preview Mermaid Support(VSCode拡張機能)

**VSCodeでMermaidを書くときの記法**
マークダウンファイルを作成して以下のような記述方法で書くことができます。

~~~sample.md
```mermaid
architecture-beta
    group public_api(cloud)[Public API]
    group private_api(cloud)[Private API] in public_api
    service database(database)[Database] in private_api
```
~~~

### アーキテクチャ図の記法
### Groups
<img width="300" alt="sample" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/cf48c565-0de7-aab9-5587-14816bc82cc7.png">

```
    group public_api(cloud)[Public API]
``` 
アイコンとタイトルを指定することができます。

<br/>

<img width="300" alt="group" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/a05940dd-a1bd-8dd8-4b30-d7da4c4d76e1.png">

```
group private_api(cloud)[Private API] in public_api
```
group内にgroupを配置する事もできます。


### Services
<img width="300" alt="services" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/d3799a43-ae6c-03ac-dd41-6e4d1d7b72de.png">

```
service database(database)[Database] in private_api
```


### EdgesとArrows
線や矢印でサービス同士を繋ぐことができます。
<img width="300" alt="edges" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/a7f26927-0e9b-c079-6a86-381650fa0e29.png">

~~~sample.md
```mermaid
architecture-beta
    group publicsubnet[Public subnet]
    group privatesubnet[Private subnet] 
    
    service ec2(logos:aws-ec2)[EC2]in publicsubnet
    service rds(logos:aws-rds)[RDS master] in privatesubnet
    
    ec2:B -- T:rds
```
~~~

```
ec2:B -- T:rds
```
ec2のbottomとrdsのtopをつなぐイメージです。

```
ec2:L --> R:rds
```
こうすると横に並べることができます。
また、```-->```みたいにすると矢印になります。

```
ec2:L -- T:rds
```
左と上を結ぶみたいな組み合わせもできます。


### Junctions
分岐を表現する事もできます。


<img width="400" alt="sample" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/0c850409-4c76-e27d-86d4-00de1fca55ea.png">

~~~sample.md
```mermaid
architecture-beta
    service left_disk(disk)[Disk]
    service top_disk(disk)[Disk]
    service bottom_disk(disk)[Disk]
    junction junctionCenter

    left_disk:R -- L:junctionCenter
    top_disk:B -- T:junctionCenter
    bottom_disk:T -- B:junctionCenter
```
~~~

分岐点をjunctionで表現して、そこから各サービスのどこに向かって繋がりを作るか指定するイメージです。

## ちょっと複雑なAWSのアーキテクチャ図を書いてみる
<details><summary>コード</summary>
sample.md

```
    architecture-beta
        group vpc[VPC]
    
        service elb(logos:aws-elb)[ELB] in vpc
    
        group availabilityzone[Availability Zone ap northeast 1a] in vpc
        group availabilityzone2[Availability Zone ap northeast 1c] in vpc
    
    
        group publicsubnet[Public subnet] in availabilityzone
        group publicsubnet2[Public subnet] in availabilityzone2
    
        service ec2a(logos:aws-ec2)[EC2]in publicsubnet
        service ec2b(logos:aws-ec2)[EC2] in publicsubnet2
    
        group privatesubnet[Private subnet] in availabilityzone
        group privatesubnet2[Private subnet] in availabilityzone2 
    
        service rds(logos:aws-rds)[RDS master] in privatesubnet
        service rds2(logos:aws-rds)[RDS slave] in privatesubnet2
    
    
        elb:B --> T:ec2a
        elb:B --> T:ec2b
        ec2a:B --> T:rds
        ec2b:B --> R:rds

```
</details>

<img width="500" alt="aws-sample" src="https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/3810533/45a2d370-a421-7080-885a-2904d4da0177.png">

ちょっとずれていますが、いい感じにできました。
draw.ioではMermaidから実際に図を作成し、それぞれの要素の位置を微調整することができます。
まだMermaidのアーキテクチャ図には対応していないので、対応されるようになったらより複雑な図を作成することも可能になるかなと思いました！


## アイコンについて
デフォルトでは```cloud```,```database```,```disk```,```internet```,```server```のアイコンを使用することができます。また設定によってiconifyのアイコンを使うこともできます。
設定の詳細は[Mermaidのドキュメント](https://mermaid.js.org/syntax/architecture#icons)を確認してください！

使えるアイコンは以下のサイトを参照

https://icon-sets.iconify.design/?query=aws


~~現在、Markdown Preview Mermaid Supportはデフォルトのロゴのみの対応だったので、今回はMarkdown Preview Mermaid Supportのコードを修正してVSCodeで使えるようにして使ってみました！ 
PRも作成しているので、マージされればVSCodeでiconifyのアイコンが使えるようになるはずです！~~
Markdown Preview Mermaid Support(VSCodeの拡張機能)で一部のアイコンが使えるようになりました！

https://github.com/mjbvz/vscode-markdown-mermaid/pull/281


## 感想
- 現状だとdraw.io,Notion,VSCodeの拡張機能などがまだ未対応なので使い所が難しいですが、それらのサービスで使えるようになったらとても便利かなと思いました。
- 複雑なアーキテクチャはMermaidで作成して、draw.ioで微調整するなどの使い方ができたら可能性が広がるなと思いました！

皆さんもぜひ使ってみてください！

## Qiitaでも使えるようになったらしい！

https://qiita.com/release-notes/2024-10-24

```mermaid
architecture-beta
        group vpc[VPC]
    
        service elb(logos:aws-elb)[ELB] in vpc
    
        group availabilityzone[Availability Zone ap northeast 1a] in vpc
        group availabilityzone2[Availability Zone ap northeast 1c] in vpc
    
    
        group publicsubnet[Public subnet] in availabilityzone
        group publicsubnet2[Public subnet] in availabilityzone2
    
        service ec2a(logos:aws-ec2)[EC2]in publicsubnet
        service ec2b(logos:aws-ec2)[EC2] in publicsubnet2
    
        group privatesubnet[Private subnet] in availabilityzone
        group privatesubnet2[Private subnet] in availabilityzone2 
    
        service rds(logos:aws-rds)[RDS master] in privatesubnet
        service rds2(logos:aws-rds)[RDS slave] in privatesubnet2
    
    
        elb:B --> T:ec2a
        elb:B --> T:ec2b
        ec2a:B --> T:rds
        ec2b:B --> R:rds

        service left_disk(disk)[Disk]
```

<details><summary>コード</summary>


```
    architecture-beta
        group vpc[VPC]
    
        service elb(logos:aws-elb)[ELB] in vpc
    
        group availabilityzone[Availability Zone ap northeast 1a] in vpc
        group availabilityzone2[Availability Zone ap northeast 1c] in vpc
    
    
        group publicsubnet[Public subnet] in availabilityzone
        group publicsubnet2[Public subnet] in availabilityzone2
    
        service ec2a(logos:aws-ec2)[EC2]in publicsubnet
        service ec2b(logos:aws-ec2)[EC2] in publicsubnet2
    
        group privatesubnet[Private subnet] in availabilityzone
        group privatesubnet2[Private subnet] in availabilityzone2 
    
        service rds(logos:aws-rds)[RDS master] in privatesubnet
        service rds2(logos:aws-rds)[RDS slave] in privatesubnet2
    
    
        elb:B --> T:ec2a
        elb:B --> T:ec2b
        ec2a:B --> T:rds
        ec2b:B --> R:rds

```
</details>


Qiitaも現状はデフォルトのアイコンのみに対応しているみたいですね！

## 参考

https://mermaid.js.org/syntax/architecture

https://qiita.com/g_ayushi/items/0e0f34d19813b8fdc2b8

---
Schooでは一緒に働く仲間を募集しています！

https://corp.schoo.jp/careers/graduates

https://corp.schoo.jp/careers