C4 アーキテクチャドキュメンテーション

C4 モデル図を Mermaid シンタックスで使用して、ソフトウェアアーキテクチャドキュメンテーションを生成します。

ワークフロー

1. スコープを理解する - オーディエンスに基づいて必要な C4 レベルを確定します
2. コードベースを分析する - システムを探索してコンポーネント、コンテナ、関係性を特定します
3. 図を生成する - 適切な抽象レベルで Mermaid C4 図を作成します
4. ドキュメント化する - 図を Markdown ファイルに記述して説明文脈を追加します

C4 図レベル

ドキュメンテーションのニーズに基づいて適切なレベルを選択します:

レベル	図タイプ	オーディエンス	表示対象	作成時期
1	C4Context	全員	システム + 外部アクター	常に（必須）
2	C4Container	技術者	アプリ、データベース、サービス	常に（必須）
3	C4Component	開発者	内部コンポーネント	価値がある場合のみ
4	C4Deployment	DevOps	インフラノード	本番システム向け
-	C4Dynamic	技術者	リクエストフロー（番号付き）	複雑なワークフロー向け

主要な洞察: 「コンテキスト図とコンテナ図のみで、ほとんどのソフトウェア開発チームには十分です。」コンポーネント/コード図は、それが本当に価値をもたらす場合にのみ作成してください。

クイックスタート例

システムコンテキスト（レベル1）

C4Context
  title System Context - Workout Tracker

  Person(user, "User", "Tracks workouts and exercises")
  System(app, "Workout Tracker", "Vue PWA for tracking strength and CrossFit workouts")
  System_Ext(browser, "Web Browser", "Stores data in IndexedDB")

  Rel(user, app, "Uses")
  Rel(app, browser, "Persists data to", "IndexedDB")

コンテナ図（レベル2）

C4Container
  title Container Diagram - Workout Tracker

  Person(user, "User", "Tracks workouts")

  Container_Boundary(app, "Workout Tracker PWA") {
    Container(spa, "SPA", "Vue 3, TypeScript", "Single-page application")
    Container(pinia, "State Management", "Pinia", "Manages application state")
    ContainerDb(indexeddb, "IndexedDB", "Dexie", "Local workout storage")
  }

  Rel(user, spa, "Uses")
  Rel(spa, pinia, "Reads/writes state")
  Rel(pinia, indexeddb, "Persists", "Dexie ORM")

コンポーネント図（レベル3）

C4Component
  title Component Diagram - Workout Feature

  Container(views, "Views", "Vue Router pages")

  Container_Boundary(workout, "Workout Feature") {
    Component(useWorkout, "useWorkout", "Composable", "Workout execution state")
    Component(useTimer, "useTimer", "Composable", "Timer state machine")
    Component(workoutRepo, "WorkoutRepository", "Dexie", "Workout persistence")
  }

  Rel(views, useWorkout, "Uses")
  Rel(useWorkout, useTimer, "Controls")
  Rel(useWorkout, workoutRepo, "Saves to")

ダイナミック図（リクエストフロー）

C4Dynamic
  title Dynamic Diagram - User Sign In Flow

  ContainerDb(db, "Database", "PostgreSQL", "User credentials")
  Container(spa, "Single-Page App", "React", "Banking UI")

  Container_Boundary(api, "API Application") {
    Component(signIn, "Sign In Controller", "Express", "Auth endpoint")
    Component(security, "Security Service", "JWT", "Validates credentials")
  }

  Rel(spa, signIn, "1. Submit credentials", "JSON/HTTPS")
  Rel(signIn, security, "2. Validate")
  Rel(security, db, "3. Query user", "SQL")

  UpdateRelStyle(spa, signIn, $textColor="blue", $offsetY="-30")

デプロイメント図

C4Deployment
  title Deployment Diagram - Production

  Deployment_Node(browser, "Customer Browser", "Chrome/Firefox") {
    Container(spa, "SPA", "React", "Web application")
  }

  Deployment_Node(aws, "AWS Cloud", "us-east-1") {
    Deployment_Node(ecs, "ECS Cluster", "Fargate") {
      Container(api, "API Service", "Node.js", "REST API")
    }
    Deployment_Node(rds, "RDS", "db.r5.large") {
      ContainerDb(db, "Database", "PostgreSQL", "Application data")
    }
  }

  Rel(spa, api, "API calls", "HTTPS")
  Rel(api, db, "Reads/writes", "JDBC")

要素シンタックス

人とシステム

Person(alias, "Label", "Description")
Person_Ext(alias, "Label", "Description")       # 外部の人
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")       # 外部システム
SystemDb(alias, "Label", "Description")         # データベースシステム
SystemQueue(alias, "Label", "Description")      # キューシステム

コンテナ

Container(alias, "Label", "Technology", "Description")
Container_Ext(alias, "Label", "Technology", "Description")
ContainerDb(alias, "Label", "Technology", "Description")
ContainerQueue(alias, "Label", "Technology", "Description")

コンポーネント

Component(alias, "Label", "Technology", "Description")
Component_Ext(alias, "Label", "Technology", "Description")
ComponentDb(alias, "Label", "Technology", "Description")

境界

Enterprise_Boundary(alias, "Label") { ... }
System_Boundary(alias, "Label") { ... }
Container_Boundary(alias, "Label") { ... }
Boundary(alias, "Label", "type") { ... }

関係性

Rel(from, to, "Label")
Rel(from, to, "Label", "Technology")
BiRel(from, to, "Label")                        # 双方向
Rel_U(from, to, "Label")                        # 上向き
Rel_D(from, to, "Label")                        # 下向き
Rel_L(from, to, "Label")                        # 左向き
Rel_R(from, to, "Label")                        # 右向き

デプロイメントノード

Deployment_Node(alias, "Label", "Type", "Description") { ... }
Node(alias, "Label", "Type", "Description") { ... }  # 短縮形

スタイリングとレイアウト

レイアウト設定

UpdateLayoutConfig($c4ShapeInRow="3", $c4BoundaryInRow="1")

• $c4ShapeInRow - 行あたりの図形数（デフォルト: 4）
• $c4BoundaryInRow - 行あたりの境界数（デフォルト: 2）

要素スタイリング

UpdateElementStyle(alias, $fontColor="red", $bgColor="grey", $borderColor="red")

関係性スタイリング

UpdateRelStyle(from, to, $textColor="blue", $lineColor="blue", $offsetX="5", $offsetY="-10")

$offsetX と $offsetY を使用して、重複する関係ラベルを修正します。

ベストプラクティス

必須ルール

1. すべての要素には以下が必須: 名前、タイプ、テクノロジー（該当する場合）、説明
2. 単方向矢印のみを使用 - 双方向矢印は曖昧さを生じさせます
3. 矢印にアクション動詞でラベル付け - 「Sends email using」、「Reads from」など、単に「uses」ではなく
4. テクノロジーラベルを含める - 「JSON/HTTPS」、「JDBC」、「gRPC」
5. 図あたり20要素以下に保つ - 複雑なシステムは複数の図に分割します

明確性ガイドライン

1. レベル1から開始 - コンテキスト図はシステムスコープのフレーム化に役立ちます
2. ファイルあたり1つの図 - 図を単一の抽象レベルに集中させます
3. 意味のあるエイリアス - 説明的なエイリアスを使用（例：s1 ではなく orderService）
4. 簡潔な説明 - 可能な限り説明を50文字以下に保ちます
5. 常にタイトルを含める - 「System Context diagram for [System Name]」

避けるべき事項

詳細なアンチパターンについては references/common-mistakes.md を参照してください:

• コンテナ（デプロイ可能）とコンポーネント（デプロイ不可）の混同
• 共有ライブラリをコンテナとしてモデリング
• メッセージブローカーを単一コンテナではなく個別トピックとして表示
• 「サブコンポーネント」のような未定義の抽象レベルを追加
• ダイアグラムを「簡潔に」するためにタイプラベルを削除

マイクロサービスガイドライン

単一チーム所有

各マイクロサービスをコンテナ（またはコンテナグループ）としてモデリングします:

C4Container
  title Microservices - Single Team

  System_Boundary(platform, "E-commerce Platform") {
    Container(orderApi, "Order Service", "Spring Boot", "Order processing")
    ContainerDb(orderDb, "Order DB", "PostgreSQL", "Order data")
    Container(inventoryApi, "Inventory Service", "Node.js", "Stock management")
    ContainerDb(inventoryDb, "Inventory DB", "MongoDB", "Stock data")
  }

複数チーム所有

別々のチームが所有する場合、マイクロサービスをソフトウェアシステムに昇格させます:

C4Context
  title Microservices - Multi-Team

  Person(customer, "Customer", "Places orders")
  System(orderSystem, "Order System", "Team Alpha")
  System(inventorySystem, "Inventory System", "Team Beta")
  System(paymentSystem, "Payment System", "Team Gamma")

  Rel(customer, orderSystem, "Places orders")
  Rel(orderSystem, inventorySystem, "Checks stock")
  Rel(orderSystem, paymentSystem, "Processes payment")

イベント駆動型アーキテクチャ

個別トピック/キューをコンテナとして表示し、単一の「Kafka」ボックスではありません:

C4Container
  title Event-Driven Architecture

  Container(orderService, "Order Service", "Java", "Creates orders")
  Container(stockService, "Stock Service", "Java", "Manages inventory")
  ContainerQueue(orderTopic, "order.created", "Kafka", "Order events")
  ContainerQueue(stockTopic, "stock.reserved", "Kafka", "Stock events")

  Rel(orderService, orderTopic, "Publishes to")
  Rel(stockService, orderTopic, "Subscribes to")
  Rel(stockService, stockTopic, "Publishes to")
  Rel(orderService, stockTopic, "Subscribes to")

出力場所

アーキテクチャドキュメンテーションを docs/architecture/ に命名規則で書き込みます:

• c4-context.md - システムコンテキスト図
• c4-containers.md - コンテナ図
• c4-components-{feature}.md - 機能ごとのコンポーネント図
• c4-deployment.md - デプロイメント図
• c4-dynamic-{flow}.md - 特定フロー向けダイナミック図

オーディエンス別の詳細度

オーディエンス	推奨図
経営層	システムコンテキストのみ
プロダクトマネージャー	コンテキスト + コンテナ
アーキテクト	コンテキスト + コンテナ + 主要コンポーネント
開発者	必要に応じたすべてのレベル
DevOps	コンテナ + デプロイメント

参考資料

• references/c4-syntax.md - 完全な Mermaid C4 シンタックス
• references/common-mistakes.md - 避けるべきアンチパターン
• references/advanced-patterns.md - マイクロサービス、イベント駆動、デプロイメント