【Mermaid.js入門】テキストで「流れ」を支配する。フローチャートとシーケンス図の基礎

そのドキュメント、本当に「生きて」いますか？

正直に答えてください。あなたが先月PowerPointで作ったシステム構成図、今のコードと一致していますか？

おそらく、Noでしょう。

なぜ図は「腐る」のか

GUIツール（PowerPoint, Cacoo, Figma）で描かれた図は、エクスポートされた瞬間に**「死んだ情報（Dead Artifact）」**になります。

1. 修正が億劫: 線の端を揃えたり、ボックスの位置を微調整するためにマウスを握る時間は、エンジニアにとって苦痛です。
2. Diffが取れない: バイナリデータや画像では、「誰が・いつ・何を」変えたのか追跡できません。
3. コードと乖離する: 結果として、ドキュメントの更新は後回しにされ、現実（コード）と乖離した「嘘の地図」が残ります。

Diagram as Code という解決策

この問題を解決する方法は一つしかありません。 **「図（Diagram）もコード（Code）として管理する」**ことです。

そのための最強のツールが、Mermaid.js です。

特徴	GUIツール (PowerPoint)	Diagram as Code (Mermaid)
入力	マウス操作（画そのものを描く）	テキスト記述（構造を記述する）
管理	バイナリ/画像（差分不可）	テキストファイル（Git管理可）
保守性	極めて低い（配置調整が地獄）	高い（自動レンダリング）
本質	お絵かき	構造設計

[!TIP] アナロジー：楽譜と演奏 GUIツールでの作図は、「録音された音楽」のようなものです。一度録音したら変更できません。 Mermaidは「楽譜」です。楽譜（コード）さえあれば、ブラウザという演奏家がいつでも最新の状態で演奏（レンダリング）してくれます。

---

1. Flowchart: 構造と分岐の地図

フローチャートはMermaidの基本です。 単なる「処理の流れ」だけでなく、システム構成やインフラ図にも使えます。

基本構文とレンダリング

graph TD
Start([開始]) --> Process[処理]
Process --> Decision{分岐?}
Decision -- Yes --> Finish([終了])
Decision -- No --> Process

これが、ブラウザ上では以下のようにレンダリングされます。

graph TD
    Start([開始]) --> Process[処理]
    Process --> Decision{分岐?}
    Decision -- Yes --> Finish([終了])
    Decision -- No --> Process

プロっぽく見せる3つのコツ

1. 形状を使い分ける:
   • [ ] 四角：基本処理
   • ([ ]) スタジアム：開始/終了（これを使うと締まります）
   • [( )] 円柱：データベース
2. 方向を意識する:
   • TD (Top-Down): プロセスや階層構造に最適。
   • LR (Left-Right): 時系列フローや、横に長いインフラ図に見やすい。
3. 接続詞をつける:
   • -->|Text| あるいは -- Text --> で線の上に文字を置けます。

---

2. Sequence Diagram: 時間と対話の譜面

「誰が」「いつ」「誰に」メッセージを送ったか。 APIの設計や、マイクロサービス間の通信を記述するならシーケンス図一択です。

ログインフローの可視化

よくあるログイン処理も、Mermaidならこれだけのコードで表現できます。

sequenceDiagram
actor User
participant FE as Frontend
participant API as Backend API
participant DB as Users DB

    User->>FE: 1. Email/Pass入力
    FE->>FE: 2. Input Validation

    alt Invalid
        FE-->>User: Show Error
    else Valid
        FE->>API: 3. POST /auth/login
        activate API
        API->>DB: SELECT * FROM users
        DB-->>API: User Data
        API-->>FE: 4. 200 OK + JWT
        deactivate API
        FE-->>User: Redirect to Home
    end

sequenceDiagram
    actor User
    participant FE as Frontend
    participant API as Backend API
    participant DB as Users DB

    User->>FE: 1. Email/Pass入力
    FE->>FE: 2. Input Validation

    alt Invalid
        FE-->>User: Show Error
    else Valid
        FE->>API: 3. POST /auth/login
        activate API
        API->>DB: SELECT * FROM users
        DB-->>API: User Data
        API-->>FE: 4. 200 OK + JWT
        deactivate API
        FE-->>User: Redirect to Home
    end

[!NOTE] 実線と点線の使い分け

• ->>: 実線矢印。リクエスト（依頼）。
• -->>: 点線矢印。レスポンス（返答）。 これを使い分けるだけで、図の「論理的な正しさ」が格段に上がります。

---

まとめ：マウスを捨てよう

今回はMermaidの基礎である「フローチャート」と「シーケンス図」を紹介しました。 これらは、システムの**「動き（Flow）」**を記述するためのツールです。

しかし、システム設計にはもう一つ、重要な側面があります。 それは**「状態（State）」と「構造（Data）」**です。

決済処理で「二重課金」が起きるのはなぜか？ それは「処理の流れ」ばかり見て、「状態の遷移」を定義していないからです。

次回、【Part 2】「状態」と「構造」をモデル化する。 バグを生まない設計のための「ステートマシン図」の極意に迫ります。