architecture-diagramlisted

# Architecture Diagram README と設計文書に入れる図を、コードから生成して保守できる形で作る。構成図（システム・サービス間・ クラウド・オンプレ）は公式アイコン付きの Diagram as Code（mingrammer/diagrams）、流れ・状態・ シーケンス・ER は Mermaid を使う。diagrams は AWS / GCP / Azure / k8s / オンプレ / SaaS / プログラミング言語 / 汎用のアイコンを同梱しており、クラウド以外の構成図にも使う。 ## 使用条件 - システム構成図、サービス間の構成、デプロイ経路、リクエストの流れを README / SPEC / docs へ入れる - 既存の図が読みに��い（アイコンと文字の比率、ラベルの重なり、GitHub 上で小さい） - 図の置き場と形式（PNG / SVG / Mermaid）を決める ## 1. 形式を決める | 図の種類 | 道具 | 理由 | |---|---|---| | 構成図（システム・サービス間・クラウド・オンプレ）、デプロイ経路 | diagrams → SVG | 公式アイコン、クラスタの入れ子、配置の自由度 | | シーケンス、状態遷移、ER、簡単な流れ | Mermaid | GitHub が描画し、ズーム操作も付く。アイコンは出ない | 完了判定: 図ごとに道具を決め、どの文書に置くかを決めた。正本は生成スクリプト（または Mermaid 本文）で、 画像を手で編集しない。 ## 2. 環境を確かめる ``` which dot || brew install graphviz # macOS。他 OS は各パッケージ管理 uv run --with diagrams python -c "import diagrams" ``` 完了判定: 両方が成功した。`brew install` は system 変更なので、実行前に一言断る。 ## 3. テンプレートから書く `assets/diagram_template.py` を `docs/diagrams/<name>.py` へコピーして書き換える。テンプレートの `svc()` は、アイコン・タイトル・補足行を Graphviz の HTML ラベルに入れる。diagrams 既定の 固定サイズノードを使わないのは、文字を大きくすると隣と重なるため（`references/pitfalls.md`）。 - 構成図は `direction="TB"`、経路図は `"LR"` から始める - 「後回し」「将来」の群は破線クラスタにし、invisible edge で最下段に固定する - 課金・危険など強調したい経路は 1 色だけ使う - ラベルは 1 行 12 文字程度。長いものは `\n` で折る 完了判定: `uv run --with diagrams python docs/diagrams/<name>.py` が SVG を出し、 `grep -c 'xlink:href="/' <svg>` が 0（アイコンが埋め込まれている）。 ## 4. 目視で確かめる SVG は画像ツールで直接読めないことがあるので、PNG に変換して見る（macOS: `qlmanage -t -s 1800 -o <dir> <svg>`）。 見る点: ラベルの重なり、矢印ラベルが別の矢印の近くに置かれていない