Mermaid.js アーキテクチャ図の構文とレイアウトガイド

アーキテクチャ図は、システムアーキテクトやDevOpsチームがインフラ構成、クラウドマイクロサービス、構造的レイアウト設定を可視化するために使用する構造化されたブループリントを提供します。architecture-betaエンジンにより、このテキストベースのツールは、構造的なサービスグループ、データベースクラスタ、ゲートウェイ、エッジパスを自動配置することで、手動のドラッグ操作を置き換え、クリーンで予測可能なシステムレイアウトを実現します。

基本的な構文構造

すべての図は、architecture-beta宣言ヘッダーから始まります。個別のノード要素をserviceキーワードを使って定義し、正確な方向性座標ポート（Top、Bottom、Left、Right）をコロンとダブルダッシュで区切って指定することで、接続トラックをマッピングします。

architecture-beta
  service gateway(internet)[Gateway Label]
  service server(server)[App Server]
  
  gateway:B -- T:server

構文リファレンス

以下の表は、Mermaid.jsでアーキテクチャワークスペースマップを構築するために使用される主なデータコンポーネント、フォーマットキーワード、およびコネクタ属性を分解しています。

高度なグループ化およびポートエッジルーティング

リンクが要素間を正確にどのように移動するかを、ごちゃごちゃにならないように制御するため、アーキテクチャエンジンは明示的なポートバインディングを必要とします。関連するノードは構造的グループ内に整理することで、システムの境界を明確にできます。

1. 精確なポートバインディング規則

接続ラインがコンポーネントから出る場所と入る場所を、コロンとエッジ方向フラグ（”T, B, L, R) をそれぞれのノード識別子に追加することで定義します：

• db:R -- L:server : ラインはデータベースの**右側**から出発し、サーバーの**左側**に直線的な水平線として進入します。
• db:T -- L:server : ラインはデータベースの**上側**から出発し、サーバーの**左側**に進入します。クリーンな90°の肘部角度で自動的に曲がります。
• src:B --> T:proc : ラインはソースノードの**下側**から出発し、方向性のある矢印先端を伴ってプロセッサの**上側**へ下方向にパスします。

2. グループによるシステムの構造化

視覚的なグループ（たとえば仮想プライベートクラウドやデータベースクラスタ）を宣言するには、groupキーワードを使用し、in修飾子を介してノードを割り当てます：

architecture-beta
  group cloudNetwork(cloud)[プライベートクラウド]
    service auth(server)[認証ノード] in cloudNetwork
    service api(server)[APIエンドポイント] in cloudNetwork

兄弟要素の整列（v11.16.0以降）

複数の異なるサービスが同一のエッジルーティング経路を共有する場合（たとえば、3つの分離されたデータソースが1つのメッセージワーカーにストリーミングする場合）、レイアウトアルゴリズムがそれらをまとめて配置してしまうことがあります。この問題を回避するには、align row と 列を整列ディレクティブは、エンジンにその兄弟要素を特定の軸線上に均等に分配するように強制します。

architecture-beta
  service src1(server)[ソース1]
  service src2(server)[ソース2]
  service proc(server)[プロセッサーハブ]

  src1:B --> T:proc
  src2:B --> T:proc

  align row src1 src2

実世界のブループリント：マイクロサービスクラスターブループリント

このブループリントは、非常に耐障害性が高く、企業向けのクラウドアーキテクチャを示しています。主なAPIエンジンを中央に配置し、認証処理と非同期タスクを左右に水平に分岐させることで、重複する線を防ぐための対称的なデザイン原則を活用しています。全体のデータフローは、公開ゲートウェイから明確に整列されたデータストレージ層へと予測可能な形で下流に流れます。行を整列ディレクティブにより、コンポーネントを鋭く、予測可能な水平方向の軌道に固定します。

architecture-beta
  title "高可用性マイクロサービスアーキテクチャ"

  %% 外部エントリ層
  service cloudflare(internet)[Cloudflare WAF]
  service alb(server)[AWS Application Load Balancer]

  %% コアアプリケーションクラスタ
  group appCluster(cloud)[マネージドEKSマイクロサービス]
    service authService(server)[認証サービス] in appCluster
    service apiService(server)[コアAPIエンジン] in appCluster
    service workerNode(server)[非同期タスクワーカー] in appCluster

  %% セキュアなストレージ層
  group dataCluster(database)[保護されたデータレイヤ]
    service redis(disk)[Redisキャッシュクラスタ] in dataCluster
    service postgres(database)[PostgreSQLプライマリ] in dataCluster

  %% 1. 垂直フロー：外部からのトラフィックが公開層から計算コアへ
  cloudflare:B --> T:alb
  alb:B --> T:apiService

  %% 2. 水平フロー：コアAPIが左右対称に分岐
  apiService:L --> R:authService
  apiService:R --> L:workerNode

  %% 3. 基準フロー：アプリワーカーが直接対応するデータスロットへ下がる
  authService:B --> T:redis
  workerNode:B --> T:postgres

  %% 完全なグリッド用のレイアウト軸の整列
  align row authService apiService workerNode
  align row redis postgres

一般的な構文の落とし穴とシステム制約

インフラストラクチャコードを書く際には、パースエラーを防ぐために、以下の特定の構成検証ルールを意識してください：

• ラベルの角括弧の順序：表示テキスト文字列は角括弧を使用する必要があります[ラベルテキスト] そして、アイコンの括弧の直後にスペースなしで続く必要があります：service id(server)[テキスト] これが正しい形式です。括弧内に引用符を使用すると、パーサーが破綻します。
• ポートの大文字小文字の区別： 接続エッジのポートアンカーは大文字で記述する必要があります（T, B, L, R). 小文字 (t, b, l, r) は認識されず、レイアウト生成のクラッシュを引き起こします。
• 事前宣言ルール： エッジパスウェイステートメント内で使用されるノードまたはジャンクション識別子は、それより上の別々の行で明示的に宣言されている必要があります。暗黙のノード名に接続しようとすると、ビルドに失敗します。
• アラインメンバー制限： 以下の align row または align column 位置指定ディレクティブを使用する場合、コマンドラインに少なくとも2つ以上の有効で、事前に宣言されたサービスまたはジャンクション識別子を指定する必要があります。