⑲ drawio (AWS 公式アイコン) でアーキテクチャ図を組み込む — Mermaid との使い分け

本シリーズではアーキテクチャ図を 3 段階 で進化させました: ASCII art → Mermaid → drawio (AWS 公式 aws4 アイコン)。それぞれの利点・欠点と、最終的にどう住み分けたかを書きます。

段階 1: ASCII art

最初は HTML の <pre> で ASCII art:

[ブラウザ]
   │
   ▼
[CloudFront] ◀── ACM (us-east-1)
   │
   ▼
[S3 バケット (非公開)]

長所	短所
編集が楽	見栄えが地味
テキストなので diff が綺麗	複雑な構造を表現できない
レンダリング不要	採用評価で「設計能力をアピール」できない

軽量だけど、ポートフォリオサイトに載せるには弱い。

段階 2: Mermaid

次に Mermaid に移行:

flowchart TD
    Browser["🌐 ブラウザ"]
    DNS["Squarespace DNS"]
    CF["CloudFront"]
    S3[("S3 Bucket")]

    Browser --> DNS
    DNS --> CF
    CF --> S3

長所	短所
テキストで書ける（diff 友好）	AWS 公式アイコンが使えない
GitHub README で native 描画	細かいレイアウト制御が困難
mermaid.js で HTML に簡単埋込	大規模図は煩雑になる
軽量（CDN 1 行で導入）

Mermaid は「テキストで管理できる図表」の決定版。GitHub README には Mermaid が最強（コードブロックに ```mermaid と書くだけで GitHub が描画してくれる）。

段階 3: drawio (AWS 公式 aws4 アイコン)

本サイト（lab.iigtn.com）の解説書には、もう一段リッチな表現がほしくて drawio に切替:

AWS 公式の aws4 アイコンセット（最新 2025 リリース）が使える
採用評価で「ちゃんと AWS Architecture Diagram を描けてる」アピール
個別アイコンに公式の色（CloudFront 紫 / S3 緑 / Lambda 橙）が付く

drawio XML はこんな感じ（抜粋）:

<mxCell id="cf" value="CloudFront" style="
  shape=mxgraph.aws4.resourceIcon;
  resIcon=mxgraph.aws4.cloudfront;
  fillColor=#8C4FFF;
  ..." vertex="1" parent="1">
  <mxGeometry x="311" y="290" width="78" height="78" as="geometry"/>
</mxCell>

長所	短所
AWS 公式アイコンが使える	XML が長くて手書きしんどい
細かいレイアウト制御可能	HTML への埋込にコツがいる
GUI エディタ（app.diagrams.net）も使える	diff が見づらい
SVG / PNG エクスポートも可能	GitHub README には不向き

aws4 アイコンの使い方

各 AWS サービスは mxgraph.aws4.resourceIcon 形式で参照します。色（fillColor）はサービスカテゴリ別:

カテゴリ	色	例
Compute	#ED7100（橙）	Lambda, EC2
Storage	#7AA116（緑）	S3, EBS
Database	#C925D1（紫桃）	DynamoDB, RDS
Networking & Content Delivery	#8C4FFF（紫）	CloudFront, Route 53
Application Integration	#E7157B（桃）	API Gateway, SNS
Security, Identity & Compliance	#DD344C（赤）	IAM, ACM, SES
Management & Governance	#E7157B（桃）	CloudWatch, CloudTrail

これを覚えておくと、AWS 公式の Architecture Diagram と整合する図が作れます。

HTML への埋込

drawio 図を Web ページにインラインで埋め込む方法は 3 つ:

iframe で viewer.diagrams.net を読み込む
SVG エクスポート して <img> で埋込
viewer-static.js でインライン描画

本サイトでは 3 番目の方式を採用:

<div class="mxgraph" data-mxgraph='{"xml": "<mxfile>...</mxfile>"}'></div>
<script src="https://viewer.diagrams.net/js/viewer-static.min.js"></script>

data-mxgraph 属性に JSON 形式で XML を埋め込むと、ページ読込時に viewer-static.js が自動で図を描画してくれる。iframe や別ファイルが要らずクリーン。

JSON エンコードの罠

drawio XML を data-mxgraph='{"xml": "..."}' に入れる時の罠:

XML 内の " は JSON 文字列として \" にエスケープ必須
HTML の単一クォート属性内なので、JSON の ' も HTML エスケープ（'）必須
改行や特殊文字も適切に処理

本シリーズでは PowerShell の ConvertTo-Json -Compress で自動変換するスクリプトを書きました:

$xml = [System.IO.File]::ReadAllText("diagram.drawio", [System.Text.Encoding]::UTF8)
$payload = @{ xml = [string]$xml; nav = $true } | ConvertTo-Json -Compress
$payload_attr = $payload -replace "'", '&#39;'

"<div class="mxgraph" data-mxgraph='$payload_attr'></div>"

これで .drawio ファイルから HTML スニペットを自動生成。

結局どう住み分けたか

場所	使うフォーマット	理由
GitHub README.md	Mermaid	GitHub が native 描画、軽量
本サイト解説書 (learn.html)	drawio (aws4 アイコン)	採用評価でリッチに見せたい
本ブログ各記事	テーブル + 適宜 Mermaid	記事の本文と diff 友好性を優先
外部公開する設計書	drawio + SVG エクスポート	クライアントへの提示物

図のソース管理

drawio ファイルもリポジトリで管理します:

frontend/diagrams/
├── 01-visitor-static.drawio
├── 02-form-flow.drawio
├── 03-deploy-flow.drawio
└── 04-overall-architecture.drawio

これらの .drawio ファイルは GitHub 上でクリックすると GitHub が自動で描画 してくれます（GitHub は drawio ネイティブサポート）。app.diagrams.net で開けば GUI で編集も可能。

「採用評価」での効果

アーキテクチャ図の質は採用評価に直結します:

ASCII art: 「最低限の説明をしている人」
Mermaid: 「コード化志向の人」「diff 管理を意識する人」
drawio + AWS 公式アイコン: 「設計書を書く文化がある人」「クライアント提案資料を作れる人」

個人サイトでも 3 つ使い分けると、技術力の幅が見える設計になります。

残りは仕上げの 2 記事。次は 「Web 系を調査した上でフリーランスポートフォリオ標準構成にサイトを再設計」 + SES 通知稼働まで を 1 記事にまとめて書きます。最終回は 付録: 構築で使ったコマンド早見表。

drawio (AWS 公式アイコン) でアーキテクチャ図を組み込む — Mermaid との使い分け