mermaid-architecture

Mermaid アーキテクチャ図

構造化された、高コントラストで本番環境にも対応できる Mermaid のアーキテクチャ図、ワークフロー、システム設計ドキュメントを作成します。ネイティブ図は Markdown ビューアー（GitHub、GitLab、Obsidian、Wiki）で直接レンダリングされます。必要に応じて、Mermaid CLI（mmdc / npx @mermaid-js/mermaid-cli）で画像（PNG/SVG）をエクスポートできます。

📁 保存場所（docs/architecture/）

生成したすべてのアーキテクチャ図、ソース .mmd ファイル、エクスポートした画像、システム設計ドキュメントは、drawio-architecture の規約に従い、必ず docs/architecture/ に保存してください。

docs/architecture/
├── system-architecture.md             # Architecture documentation with embedded Mermaid blocks
├── <name>_<type>_<title>.mmd          # Source Mermaid definitions
├── <name>_<type>_<title>.png          # Optional exported raster image
└── <name>_<type>_<title>.svg          # Optional exported vector image

保存する前に、ディレクトリが存在することを確認してください。

mkdir -p docs/architecture

使用する場面

• ユーザーがアーキテクチャ図、システム構造、コンポーネント概要、C4 モデル、マイクロサービスのトポロジー、またはデータフローを求めている場合。

• API のやり取り、サービス呼び出しシーケンス、認証フロー、またはリクエストのライフサイクルをドキュメント化する場合。

• ワークフロー、ステートマシン、ビジネスロジック、ETL パイプライン、または決定木を可視化する場合。

• コードを図にマッピングする場合（Spring Boot、FastAPI、React、Node/Express、Python ETL、Java）。

• 完全な設計ドキュメント（システム設計、アーキテクチャ、API 設計、データベーススキーマ）を作成または更新する場合。

• **Orchestrator パイプライン（Phase 5）**では、ネイティブの Markdown Mermaid 図を更新または生成するために、docs/architecture/ の管理を担う包括的なスキルである /architecture 経由で呼び出されます。

• ユーザーがこのスキルについて英語で依頼または言及している場合（例：「use /mermaid-architecture」「run mermaid-architecture」「generate mermaid diagram」）。

• ユーザーがこのスキルについてポルトガル語で依頼または言及している場合（例：「use /mermaid-architecture」「execute mermaid-architecture」「gerar diagrama mermaid」）。

使用しない場面

• ネイティブの .drawio 形式による、ドラッグ＆ドロップでの視覚的な編集 → /drawio-architecture を使用してください。
• フリーハンドのスケッチや簡易的なホワイトボード図 → Excalidraw または tldraw を使用してください。
• PlantUML 固有のレガシー図（Salt ワイヤーフレーム、タイミング図）。

Orchestrator との統合

Orchestrator のライフサイクル（Phase 5 — 検証と QA ゲート）では、オーケストレーターが /architecture を呼び出し、作業を専門エンジンに振り分けます。

1. /drawio-architecture は、視覚的に編集可能な .drawio のシステム図を更新します。
2. /mermaid-architecture はその直後に実行され、docs/architecture/ 内のネイティブ Mermaid アーキテクチャ図と埋め込み Markdown ファイルを生成または更新します。
3. /create-readme はその後、生成された図を README.md で参照します。

---

図の種類と選択ガイド

図の種類	主な用途	読み込むガイド
Architecture / C4	システムコンテキスト、コンテナー、マイクロサービス、コンポーネントの境界	references/guides/diagrams/architecture-diagrams.md
Sequence	API のやり取り、認証フロー、サービス間メッセージング、非同期イベント	references/guides/diagrams/sequence-diagrams.md
Activity / Flowchart	ビジネスプロセス、承認パイプライン、ETL ステージ、決定木	references/guides/diagrams/activity-diagrams.md
Deployment / Cloud	クラウドインフラストラクチャ（AWS、Azure、GCP）、Kubernetes、ネットワーク	references/guides/diagrams/deployment-diagrams.md
Class / ER / State	データモデル、データベーススキーマ、ライフサイクルの遷移	references/guides/wiki-ticket-and-github.md

---

エラー復旧に対応した堅牢なワークフロー

構文エラーがドキュメントに混入するのを防ぐため、復旧機能を備えた次の検証サイクルに従ってください。

flowchart LR
    A[1. Identify Diagram Type] --> B[2. Save .mmd to docs/architecture]
    B --> C{3. Validate Syntax}
    C -->|Valid| D[4. Embed in Markdown / Export]
    C -->|Invalid| E[5. Search Troubleshooting]
    E --> F[6. Apply Fix & Retry]
    F --> C

    classDef step fill:#90EE90,stroke:#333,color:darkgreen
    classDef decision fill:#FFD700,stroke:#333,color:black
    class A,B,D,E,F step
    class C decision

スクリプトの実行

同梱の堅牢なスクリプトを使って、図を docs/architecture/ に直接生成してください。

# Generate diagram with automatic syntax validation and image export
python3 skills/mermaid-architecture/scripts/resilient_diagram.py \
    --code "flowchart TD; A[Client] --> B[API Gateway]" \
    --output-dir docs/architecture \
    --markdown-file system_architecture \
    --diagram-num 1 \
    --title "overview" \
    --format png \
    --json

mmdc がグローバルにインストールされていない場合、スクリプトは自動的に npx -y @mermaid-js/mermaid-cli を使用します。

---

高コントラストのスタイル（必須）

すべての図で、各 classDef に必ず color: を指定し、明るい背景と暗い背景のどちらでもテキストが読みやすくなるようにしてください。

graph TB
    classDef primary fill:#90EE90,stroke:#333,stroke-width:2px,color:darkgreen
    classDef secondary fill:#87CEEB,stroke:#333,stroke-width:2px,color:darkblue
    classDef database fill:#E6E6FA,stroke:#333,stroke-width:2px,color:darkblue
    classDef error fill:#FFB6C1,stroke:#DC143C,stroke-width:2px,color:black

    %% Rule: Every classDef MUST include color: property

---

セマンティックな Unicode 記号

視認性と明瞭さを高めるため、常に Unicode 記号を取り入れてください。

• 👤 ユーザー：👤 User、👨‍💼 Admin
• 🌐 ネットワーク：🌐 Load Balancer、🌐 API Gateway、☁️ Cloud
• ⚙️ コンピューティング：⚙️ Service、⚡ Worker、🚀 Microservice
• 💾 ストレージ：[(💾 Database)]、[(⚡ Redis Cache)]、📦 Object Storage
• 📨 メッセージング：📨 Event Bus、📬 Message Queue、📢 PubSub
• 🔐 セキュリティ：🔐 Auth Service、🛡️ Firewall、🔑 Secrets
• 📊 オブザーバビリティ：📊 Metrics、📝 Logs、🚨 Alerts

---

コードからの図の生成

既存のソースコードからアーキテクチャを生成する場合：

1. エントリーポイントを分析する：コントローラー、ルート、API 仕様（@RestController、@app.get、Express のルート、Controllers）を読み取ります。
2. サービスの依存関係をたどる：注入されたサービス、リポジトリ、メッセージキュー、DB コンテキストをたどります。
3. インフラストラクチャを把握する：docker-compose.yml、Helm チャート、Terraform、クラウド設定を読み取ります。
4. ビューを選択する：
   • 高レベルのコンポーネントトポロジー → architecture-diagrams.md
   • メソッド／呼び出しフロー → sequence-diagrams.md
   • ビジネス上の状態遷移 → activity-diagrams.md
5. examples/ のフレームワークテンプレート（spring-boot、fastapi、react、node-webapp、python-etl、java-webapp）を参照します。

---

設計ドキュメントのテンプレート（assets/）

アーキテクチャまたはシステム全体のドキュメントが必要な場合は、該当するテンプレートに内容を記入し、docs/architecture/ に保存します。

ドキュメントの種類	テンプレートのパス	出力先
アーキテクチャ設計	assets/architecture-design-template.md	docs/architecture/architecture-design.md
システム設計	assets/system-design-template.md	docs/architecture/system-design.md
API 設計	assets/api-design-template.md	docs/architecture/api-design.md
データベース設計	assets/database-design-template.md	docs/architecture/database-design.md
機能設計	assets/feature-design-template.md	docs/architecture/feature-<name>-design.md

---

Python ユーティリティ

このスキルには、scripts/ にスタンドアロンのユーティリティが含まれています。

# Extract diagrams from markdown, validate, or convert
python3 skills/mermaid-architecture/scripts/extract_mermaid.py docs/architecture/system.md --validate

# Convert .mmd to PNG or SVG
python3 skills/mermaid-architecture/scripts/mermaid_to_image.py docs/architecture/overview.mmd docs/architecture/overview.png

# Full resilient generation with error diagnostics
python3 skills/mermaid-architecture/scripts/resilient_diagram.py --code "..." --title "service_map"

---

参考資料

• references/guides/diagrams/architecture-diagrams.md — C4 モデル、マイクロサービス、コンポーネントアーキテクチャ
• references/guides/diagrams/sequence-diagrams.md — API のやり取り、サービス呼び出し
• references/guides/diagrams/activity-diagrams.md — ワークフローとプロセス
• references/guides/diagrams/deployment-diagrams.md — クラウド、インフラストラクチャ、デプロイ
• references/guides/unicode-symbols/guide.md — セマンティック記号の完全な一覧
• references/guides/troubleshooting.md — よくある構文エラー 28 種類の解決方法
• references/guides/resilient-workflow.md — エラー復旧と検証の手順
• architecture — docs/architecture/ を管理し、図の作成作業をこのエンジンに割り当てる包括的なスキル
• drawio-architecture — 編集可能な draw.io のビジュアル図を作成するための連携スキル