aws-architecture-diagram

AWS アーキテクチャ図スキル

AWS 公式アーキテクチャアイコンを使用して、ネイティブな .drawio ファイルとして AWS アーキテクチャ図を生成します。必要に応じて、埋め込み XML を含む PNG、SVG、PDF にエクスポートできます（エクスポートしたファイルも draw.io で編集できます）。

図の作成方法

1. 以下のルールに従って、mxGraphModel 形式の draw.io XML を生成します
2. Write ツールを使って、XML を .drawio ファイルに書き込みます
3. ユーザーがエクスポート形式を指定した場合（png、svg、pdf）は、draw.io CLI を使ってエクスポートします（「エクスポート」セクションを参照）
4. open（macOS）、xdg-open（Linux）で結果を開くか、パスを出力します

レイアウトルール

• データ／リクエストの経路は左から右へのフローにします
• UI／フロントエンドは左側に配置します（ユーザーは左側からアクセスします）
• データソース／外部システムは右側に配置します
• 並行する経路には水平レーン（上のレーン、下のレーン）を使用します
• アイコン間は水平方向に最低 220px の間隔を確保します（エッジラベル用のスペース）
• レーン間は垂直方向に最低 250px の間隔を確保します
• セカンダリ／補助サービス（モニタリング、DLQ）は、メインフローの下に 280px 以上の間隔を空けて配置します
• キャンバス：pageWidth="2400" pageHeight="1400"、ビューポートは dx="2800" dy="1600"
• 背景の長方形の後に、必ずタイトルブロックを含めます：

<mxCell value="&lt;b&gt;Diagram Title&lt;/b&gt;&lt;br&gt;Author | Date | Version" style="text;html=1;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=14;spacing=8;" vertex="1" parent="1">
  <mxGeometry x="40" y="30" width="420" height="60" as="geometry" />
</mxCell>

アイコンのスタイル

• アイコンには draw.io 内蔵の mxgraph.aws4 ステンシルライブラリを使用します。これはAWS 公式アーキテクチャアイコンです（https://aws.amazon.com/architecture/icons/）
• アイコンのサイズ：メインサービスは 78x78px、セカンダリサービスは 65x65px
• すべてのアイコンで sketch=0 を使用します
• すべての AWS サービスアイコンで strokeColor=#ffffff を使用します
• ラベルのフォントサイズ：12px
• グループボックスに色付きの背景は使用しません。常に fillColor=none を使用します

3D／アイソメトリック図 — 別のアイコンライブラリを使用する

ユーザーが3D、アイソメトリック、または「AWS 3D」図を求めている場合、平面的な aws4 アイコンを手作りのプラットフォーム／台座の形状に配置して、3D 風に見せてはいけません。draw.io には、これ専用の別の組み込みライブラリ mxgraph.aws3d.* があります。

• アイコンを選ぶ前に references/aws-icons-3d.md を読み込みます。このファイルには、検証済みのシェイプ一覧、スタイルのプレフィックス、サイズ、ネイティブの isometricEdgeStyle エッジテンプレートが記載されています。
• このライブラリは 2019 年以前の旧アイコンセットで、aws4 より収録範囲がかなり狭く（API Gateway、ECS/EKS/Fargate、Step Functions、EventBridge、SNS、Aurora、CloudWatch、IAM などはありません）、存在するアイコンを確認してから使用してください。代替アイコンを使う場合は、ステンシル名を推測せず、ユーザーにその旨を伝えてください。
• AWS 固有のアイコンがない一般的なハードウェア（クライアント、オンプレミスサーバー、ラック、スイッチ）については、別途バンドルされているアイソメトリック画像ライブラリ references/aws-icons-allied-telesis.md を参照してください。このライブラリで不足分を補えます。
• これらのアイコン自体がすでに 3D です。ノード間に斜めのオフセットを付け、上昇するアイソメトリックな階段状に配置し、下に偽のプラットフォームを追加しないでください。
• コネクターには orthogonalEdgeStyle ではなく、edgeStyle=isometricEdgeStyle を使用します（矢印の先端を確実に表示するには、endArrow=block で上書きします）。

エッジのスタイル — 見やすい図を作成するために重要

基本のエッジスタイル：

edgeStyle=orthogonalEdgeStyle;rounded=1;orthogonalLoop=1;jettySize=auto;html=1;strokeWidth=2;exitX=1;exitY=0.5;exitDx=0;exitDy=0;entryX=0;entryY=0.5;entryDx=0;entryDy=0;

エッジラベルのルール：

• ラベルは短くします（最大1～2語）。詳細はエッジラベルではなく、アイコンのラベルに記載します。
• ラベル付きのエッジには、必ず labelBackgroundColor=#F5F5F5;fontSize=11; を追加します。
• ラベルのないエッジでは、value を完全に省略します。
• ラベルを付けない場合：フローが明らかな場合（Lambda → DynamoDB に「書き込み」というラベルは不要）

メインフローの上または下にあるサービスへのエッジには、明示的な出口／入口ポイントを使用します：

• 下から出る：exitX=0.5;exitY=1;exitDx=0;exitDy=0;
• 上から入る：entryX=0.5;entryY=0;entryDx=0;entryDy=0;
• これにより、draw.io が他のアイコンを通るように線を引くのを防げます。

エッジの種類：

• 実線（strokeWidth=2）：主要なデータフロー
• 破線（strokeWidth=2;dashed=1;）：オプション／非同期
• 赤い破線（strokeWidth=2;dashed=1;strokeColor=#DD344C;）：エラーパス

エッジの接続（重要 — 「緑の十字」問題を解決）：

• すべてのエッジには、有効なセルIDを参照する source="<cell-id>" 属性と target="<cell-id>" 属性の両方を必ず指定します。
• 接続されていないエッジは絶対に作成しないでください。すべてのエッジの両端を図形に接続します。
• 図形の外周にある正確な接続ポイントを定義するため、必ず exitX/exitY と entryX/entryY を指定します。
• コンテナ間のエッジ： 始点と終点が異なるコンテナ内にある場合、エッジの parent="1" を設定します。

視覚的な品質：直線の矢印、重なりのない配置、プロフェッショナルなレイアウト

アイコンが正しくても、レイアウトが雑な図はプロフェッショナルに見えません。仕上げる前に、すべての図が以下のルールに沿っているか確認してください。曖昧な「見栄えをよくする」ための助言ではなく、意図的に具体的で確認可能なルールです。

• ノードを一貫した軸にそろえ、エッジを単一の直線セグメントにします。 フロー内で隣り合うノード間の水平または垂直方向の差を一定に保ち（同じレーンの y 座標、同じ列間隔）、接続エッジが折れ曲がるのではなく、すっきりした一本の線として描画されるようにします。
• 分岐ノードや二次ノードを、親ノードとまったく同じ中心線上に配置します。 ノードが垂直方向に分岐する場合（たとえば、メインフローの下に補助サービスを配置する場合）、その水平中心を親ノードの水平中心に正確に合わせます。目測ではなく、child.x = parent.center_x - child.width/2 を計算してください。数ピクセルのずれでも、「真下」に伸びるエッジが目立って斜めに見えてしまいます。
• エッジの折れ曲がりは最大1か所にし、できれば0か所にします。 障害物を避けるために計算したエッジ経路で2回以上の折れ曲がりが必要になる場合は、レイアウトに問題があります。迂回するために折れ曲がりを増やすのではなく、ノードを移動してください。
• エッジを、接続先ではないアイコンのバウンディングボックス内に通してはいけません。 座標を最終決定する前に、各エッジの経路が接続先ではないすべてのアイコンの (x, y, width, height) の矩形を通過しないか確認してください。通過する場合は、ノードを移動するか、明示的な出口／入口を追加して経路を迂回させます。
• 2本のエッジを重ねたり、視覚的に融合させたりしてはいけません。 2本のエッジが同じ経路（たとえば、同じ2つのレーン間の平行な2つのフロー）を通る場合は、出口／入口を変えるか、明示的な中間点を設けて間隔が見えるようにずらします。
• エッジの交差は全体として最小限に抑えます。 データの実際の流れに沿ってノードを配置し、エッジ同士が交差しにくくします。交差が避けられない場合（たとえば、フィードバック／応答経路）は、別のエッジと重ねるのではなく、目に見えるようにずらして経路を引きます。
• 間隔は「十分」で済ませず、一貫性を保ちます。 フロー内で隣り合うノード間の最小間隔をすべて同じにします。技術的には何も重なっていなくても、間隔が 400px の箇所と 250px の箇所がある図は雑に見えます。
• キャンバス上の構成バランスを整えます。 ページの片側だけが密で、もう片側が空く状態を避け、実際のコンテンツと一貫した余白に合わせてキャンバスのサイズを調整します。
• 仕上げる前にセルフチェックします。 すべての座標を配置した後、各エッジを始点から終点まで頭の中でたどり、（1）アイコンを横切らない、（2）別のエッジと重ならない、（3）折れ曲がりが最大1か所である、（4）両端が接続先のアイコンにぴったり接している、ことを確認します。どれか1つでも満たさない場合は、意図だけでなくレイアウトを修正してください。

PNG エクスポートの背景

ルートセルの後に配置する最初の要素（最も低い z-order）：

<mxCell value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#F5F5F5;strokeColor=none;" vertex="1" parent="1">
  <mxGeometry x="0" y="0" width="2400" height="1400" as="geometry" />
</mxCell>

AWS アイコンのパターン（動作確認済み）

resourceIcon（78x78、色付きの四角いフレーム）

サービス	resIcon	fillColor
Lambda	mxgraph.aws4.lambda	#ED7100
API Gateway	mxgraph.aws4.api_gateway	#E7157B
EventBridge	mxgraph.aws4.eventbridge	#E7157B
SNS	mxgraph.aws4.sns	#E7157B
SES	mxgraph.aws4.simple_email_service	#DD344C
Step Functions	mxgraph.aws4.step_functions	#E7157B
DynamoDB	mxgraph.aws4.dynamodb	#C925D1
RDS	mxgraph.aws4.rds	#C925D1
S3	mxgraph.aws4.s3	#7AA116
CloudFront	mxgraph.aws4.cloudfront	#8C4FFF
Route 53	mxgraph.aws4.route_53	#8C4FFF
ECS	mxgraph.aws4.ecs	#ED7100
EC2	mxgraph.aws4.ec2	#ED7100

スタイルテンプレート：

sketch=0;points=[[0,0,0],[0.25,0,0],[0.5,0,0],[0.75,0,0],[1,0,0],[0,1,0],[0.25,1,0],[0.5,1,0],[0.75,1,0],[1,1,0],[0,0.25,0],[0,0.5,0],[0,0.75,0],[1,0.25,0],[1,0.5,0],[1,0.75,0]];outlineConnect=0;fontColor=#232F3E;fillColor=<COLOR>;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.<SERVICE>

productIcon（70x100、サービスのヘッダーバー付きの縦長アイコン）

サービス	prIcon
SQS	mxgraph.aws4.sqs

スタイルテンプレート：

sketch=0;outlineConnect=0;fontColor=#232F3E;gradientColor=none;strokeColor=#ffffff;fillColor=#232F3E;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;whiteSpace=wrap;fontSize=12;fontStyle=0;shape=mxgraph.aws4.productIcon;prIcon=mxgraph.aws4.<SERVICE>

単独の図形（resIcon は不要です）

図形	shape value	fillColor
クライアント／ブラウザー	mxgraph.aws4.client	#232F3D
従来型サーバー	mxgraph.aws4.traditional_server	#232F3D
ファイアウォール	mxgraph.aws4.generic_firewall	#232F3D
ALB	mxgraph.aws4.application_load_balancer	#8C4FFF
NLB	mxgraph.aws4.network_load_balancer	#8C4FFF
VPC エンドポイント	mxgraph.aws4.endpoints	#8C4FFF

グループ境界

グループ	grIcon	strokeColor
AWS Cloud	mxgraph.aws4.group_aws_cloud_alt	#232F3E
アカウント	mxgraph.aws4.group_account	#CD2264
オンプレミス	mxgraph.aws4.group_on_premise	#5A6C86
企業データセンター	mxgraph.aws4.group_corporate_data_center	#388E3C
VPC	mxgraph.aws4.group_vpc2	#8C4FFF
サブネット（パブリック）	mxgraph.aws4.group_security_group	#7AA116
サブネット（プライベート）	mxgraph.aws4.group_security_group	#147EBA

コンテナーの入れ子（グループ化に不可欠）：

• すべてのグループ／境界図形のスタイルには、container=1;dropTarget=1; を必ず含めてください
• 境界内の子セルでは、parent="1" ではなく parent="<boundary-cell-id>" を設定してください
• これにより、境界を移動すると、すべての子要素も一緒に移動します
• 子要素のジオメトリ座標は、キャンバスではなく親コンテナーを基準とします
• コンテナーをまたぐエッジ： ソースとターゲットが異なるコンテナー内にある場合は、エッジの parent="1" を設定してください

動作しないアイコン — 使用禁止

• resIcon=mxgraph.aws4.dynamodb_table — 色付きの空の四角形として描画されます
• resIcon=mxgraph.aws4.dynamodb_stream — 色付きの空の四角形として描画されます
• resIcon=mxgraph.aws4.general_saml_token — 黒い四角形として描画されます
• resIcon=mxgraph.aws4.endpoint — 描画されない場合があります
• resIcon=mxgraph.aws4.kinesis_data_streams — 動作が不安定です

代替手段：

• DynamoDB のテーブル／ストリーム → resIcon=mxgraph.aws4.dynamodb を使用し、説明的なラベルを付けます
• 外部システム → shape=mxgraph.aws4.traditional_server を使用します
• ブラウザー／クライアント → shape=mxgraph.aws4.client を使用します

対象読者モード

生成する前に、対象読者を確認してください。

• 技術者向け：サービス名、プロトコルのラベル（HTTPS、gRPC）、CIDR ブロック、インスタンスタイプを使用します
• 非技術者向け：アクションのラベル（「データを保存」「通知を送信」）を使用し、実装の詳細を隠して、番号付きのフロー（① ② ③）を使用します

不明な場合は、「技術者向けですか、それとも経営層／非技術者向けですか？」と尋ねてください。

番号付きフローのエッジ（非技術者向けモード）

技術的なラベルの代わりに、丸数字でフローの順序を示します。

• フロー A：① → ② → ③ → ④（白抜きの丸数字）
• フロー B：❶ → ❷ → ❸ → ❹（2 つ目のフローには黒塗りの丸数字）

エッジラベルには、value="①" と fontSize=14;fontStyle=1;labelBackgroundColor=#ffffff; を使用します。

付属ガイド

.drawio ファイルを生成した後、Markdown 形式のガイドも生成してください。

• 同じファイル名で、拡張子を .md にします
• 内容：図のタイトル、フローの説明（番号付き手順）、サービス一覧とその目的、主要な設計上の判断

2 段階の編集手順

最初の .drawio ファイルを生成した後：

1. draw.io CLI を使用して PNG にエクスポートします（「エクスポート」セクションを参照）
2. PNG を目視で確認します — 空または壊れたアイコン、重なったエッジ、ずれたラベルがないか確認してください
3. .drawio XML の問題を修正し、再エクスポートします

これにより、生の XML では見つけられない描画上の問題（ステンシル名の誤り、壊れたスタイル）を検出できます。

アイコン名に関する注意 — 重大

draw.io のステンシル名は、現在の AWS サービス名と必ずしも一致しません。名前が変更されたサービスでは、以前のステンシル名がそのまま使われています。

AWS サービス名	draw.io resIcon 名	理由
Amazon OpenSearch Service	elasticsearch_service	2021 年に Elasticsearch から名称変更されました。opensearch_service も使用できます
Amazon EventBridge	eventbridge	以前は CloudWatch Events でした
AWS Fargate	fargate	正しい名前です
VPC ピアリング	peering	リソースレベル：shape=mxgraph.aws4.peering;strokeColor=none — vpc_peering や peering_connection ではありません（空の四角形として描画されます）
Amazon MSK	managed_streaming_for_kafka	msk ではありません（空の四角形として描画されます）
IAM Identity Center	single_sign_on	iam_identity_center ではありません（空の四角形として描画されます）

ルール： アイコン名は必ず参照ファイルで確認してください。サービスアイコンが空のボックスとして描画される場合は、ステンシル名が間違っています。正規の名前は、draw.io のソースにある src/main/webapp/js/diagramly/sidebar/Sidebar-AWS4.js で確認してください（旧 3D／アイソメトリックライブラリの場合は Sidebar-AWS3D.js、汎用ハードウェア画像ライブラリの場合は Sidebar-AlliedTelesis.js を確認してください。3D ライブラリの図形名はキャメルケースです。例：dynamodb ではなく dynamoDb）。

マッピングされていないサービスのフォールバック： どの参照ファイルにもサービスが見つからない場合は、サービス名をラベルとして付けた汎用 AWS クラウドアイコンを使用してください。

sketch=0;outlineConnect=0;fontColor=#232F3E;fillColor=#232F3E;strokeColor=#ffffff;dashed=0;verticalLabelPosition=bottom;verticalAlign=top;align=center;html=1;fontSize=12;fontStyle=0;aspect=fixed;shape=mxgraph.aws4.resourceIcon;resIcon=mxgraph.aws4.general_AWScloud

不明なサービスを、ラベルのない単色の四角形として描画しないでください。

検証手順

XML の生成後、次の項目を確認してください。

1. すべての resIcon= 値が参照ファイルに存在する
2. サービスレベルのアイコンに strokeColor=#ffffff が指定されている
3. リソースレベルのアイコンに strokeColor=none が指定されている
4. XML コメントが含まれていない
5. すべてのセル ID が一意である
6. すべてのエッジに <mxGeometry relative="1" as="geometry" /> がある
7. 推測したステンシル名を使用したアイコンがない — すべて参照ファイルと照合済みである
8. すべてのエッジに、有効なセル ID を参照する source 属性と target 属性の両方がある（宙に浮いたエッジがない）
9. すべてのグループ／境界図形のスタイルに container=1;dropTarget=1; が含まれている
10. 境界内の子要素では parent="1" ではなく parent="<boundary-id>" を使用している

エクスポート

draw.io Desktop CLI を使用した PNG／SVG／PDF のエクスポート：

複数ページの図

複雑なアーキテクチャでは、1 つの .drawio ファイル内に複数のページを使用してください。

<mxfile>
  <diagram id="overview" name="Overview">...</diagram>
  <diagram id="networking" name="Networking Detail">...</diagram>
  <diagram id="data-flow" name="Data Flow">...</diagram>
</mxfile>

• ページ 1：概要（サービスレベルのアイコンのみ）
• ページ 2 以降：詳細ビュー（リソースレベルのアイコン、サブネットのレイアウトなど）

凡例／タイトルブロック

背景の四角形の内側、左上隅に配置してください。

<mxCell value="&lt;b&gt;Diagram Title&lt;/b&gt;&lt;br&gt;Author | Date | Version" style="text;html=1;align=left;verticalAlign=top;whiteSpace=wrap;rounded=0;fontSize=14;spacing=8;" vertex="1" parent="1">
  <mxGeometry x="40" y="40" width="300" height="50" as="geometry" />
</mxCell>

PNG エクスポート時の背景の修正

エクスポート時に背景が黒くなるのを防ぐため、図全体を覆う #F5F5F5 の四角形を最背面の要素として配置してください。

エクスポート CLI

プラットフォーム	CLI パス
macOS	/Applications/draw.io.app/Contents/MacOS/draw.io
Linux	drawio（snap/apt 経由で PATH に設定）
Windows	"C:\Program Files\draw.io\draw.io.exe"

<CLI> -x -f <format> -e -b 10 -o <output> <input>

フラグ：-x はエクスポート、-f は形式（png/svg/pdf）、-e は図の XML を埋め込み、-b 10 は境界線です。

エクスポートされたファイルの拡張子は二重になります：name.drawio.png — XML が埋め込まれていることを示し、draw.io で再編集できます。

XML の整形式性（重大）

• XML コメント（``）は絶対に含めないでください — パースエラーの原因になります
• 特殊文字をエスケープしてください：& < > "
• 各 mxCell に一意の id 値を必ず使用してください
• すべてのエッジに、子要素として <mxGeometry relative="1" as="geometry" /> が必ず必要です
• ルート構造には、id="0"（ルート）と id="1"（デフォルトレイヤー、parent="0"）のセルが必要です

公式リファレンス

• XML リファレンス：https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/xml-reference.md
• スタイルリファレンス：https://raw.githubusercontent.com/jgraph/drawio-mcp/main/shared/style-reference.md