【Mermaid.js実践】「カオス」を美しく手懐ける。大規模アーキテクチャとスタイリング

Part 1とPart 2で、Mermaidの文法はマスターしました。しかし、いざ実務で大規模システムの構成図を描こうとすると、多くの人が壁にぶつかります。

なぜあなたの図は「スパゲッティ」なのか

ノードが10個を超えたあたりから、線が交差し、配置が崩れ、**「見るだけで頭が痛くなる図（Cognitive Overload）」**が出来上がります。スパゲッティ化した図は、ない方がマシです。誰も読みたくないし、メンテもされません。

解決策：都市計画（City Planning）としての作図

大規模な図を描く鍵は、**「区画整理（Zoning）」**です。都市に住宅街、商業区、工業地帯があるように、システム図にも「役割ごとの区画」が必要です。

これを実現するのが Mermaid の Subgraph 機能です。

比較項目	スパゲッティ図	アーキテクチャ図
構造	フラット（全ノードが並列）	階層的（意味の塊がある）
視線	あちこちに飛ぶ	大きな塊から詳細へ
アナロジー	迷路	地図

6. Subgraph: カオスの整理整頓

ただ subgraph で囲むだけではありません。「何で囲むか」という戦略が重要です。

レイヤー化の例（Frontend / Backend / Infra）

graph TB
subgraph "Public Layer"
Browser
App
end

    subgraph "Private Network"
        API
        DB
    end

    Browser --> API

このように「境界線」を可視化することで、セキュリティの境界やネットワークの区分が一目でわかります。

7. Styling: 図に「感情」を宿す

デフォルトのMermaidは、質実剛健ですが「味気ない」です。重要なサーバー、危険な操作、外部システム……それらに色をつけることで、図は**「感情（Vibe）」**を持ち始めます。

ClassDefによる一括指定

個別にスタイルを書くのはやめましょう。CSSのようにクラスを定義します。

graph LR
%% クラス定義
classDef danger fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
classDef safe fill:#e6f7ff,stroke:#1890ff;

    User:::safe --> API:::safe
    API --> LegacySystem[レガシー基盤]:::danger

graph LR
    classDef danger fill:#ffcccc,stroke:#ff0000,stroke-width:2px;
    classDef safe fill:#e6f7ff,stroke:#1890ff;

    User:::safe --> API:::safe
    API --> LegacySystem[レガシー基盤]:::danger

[!TIP] 色の意味論（Semantics）

赤: 危険、障害点、外部依存、レガシー。

青/緑: 正常系、自社システム、新規機能。

グレー: データベース、インフラ、背景情報。色のルールを統一するだけで、読み手の理解スピードは2倍になります。

8. 実践：マイクロサービス・アーキテクチャ

最後に、これまで学んだ全ての技術（Flow, Subgraph, Styling）を統合した例をご覧ください。

%%{init: {'theme': 'base', 'themeVariables': { 'primaryColor': '#fff', 'edgeLabelBackground':'#fff'}}}%%
graph TD
    classDef db fill:#eee,stroke:#999,stroke-width:1px;
    classDef svc fill:#e6f7ff,stroke:#1890ff,stroke-width:2px;

    User([User]) --> LB{Load Balancer}

    subgraph "Cluster A: Core"
        LB --> API[Auth Service]:::svc
        API --> DB[(User DB)]:::db
    end

    subgraph "Cluster B: Analytics"
        API -.-> Kafka[Msg Queue]
        Kafka --> Workers[Data Workers]:::svc
        Workers --> DWH[(Data Warehouse)]:::db
    end

完結にあたって

全3回の「Mermaid.js Masterclass」にお付き合いいただき、ありがとうございました。

Part 1: マウスを捨て、テキストで「流れ」を描く。
Part 2: 「状態」と「構造」でロジックを固める。
Part 3: サブグラフとスタイルで「カオス」を飼いならす。

これで、あなたはもう「なんとなく図を書いている人」ではありません。コードと同じように、図を設計し、実装し、リファクタリングできる**「アーキテクト」**です。

さあ、あなたのリポジトリにある古びた .pptx を削除して、.md ファイルを作りましょう。 Code represents Logic. Diagrams represent Wisdom.