c4-architecture

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

Mermaid 構文の C4 モデル図を使って、ソフトウェアアーキテクチャのドキュメントを生成します。

ワークフロー

1. スコープを把握する - 想定読者に基づき、必要な C4 レベルを決定する
2. コードベースを分析する - システムを調査し、コンポーネント、コンテナ、関係を特定する
3. 図を生成する - 適切な抽象度で Mermaid C4 図を作成する
4. ドキュメント化する - 図を説明文を添えて Markdown ファイルに書き出す

C4 図のレベル

ドキュメントの必要性に応じて適切なレベルを選択してください。

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

重要な考え方: 「Context 図と Container 図は、ほとんどのソフトウェア開発チームにとって十分です。」Component 図やCode 図は、本当に価値がある場合にのみ作成してください。

クイックスタートの例

システムコンテキスト（レベル 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")       # External person
System(alias, "Label", "Description")
System_Ext(alias, "Label", "Description")       # External system
SystemDb(alias, "Label", "Description")         # Database system
SystemQueue(alias, "Label", "Description")      # Queue system

コンテナ

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")                        # Bidirectional
Rel_U(from, to, "Label")                        # Upward
Rel_D(from, to, "Label")                        # Downward
Rel_L(from, to, "Label")                        # Leftward
Rel_R(from, to, "Label")                        # Rightward

デプロイメントノード

Deployment_Node(alias, "Label", "Type", "Description") { ... }
Node(alias, "Label", "Type", "Description") { ... }  # Shorthand

スタイルとレイアウト

レイアウト設定

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

• $c4ShapeInRow - 1行あたりの図形数（デフォルト: 4）
• $c4BoundaryInRow - 1行あたりの境界数（デフォルト: 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. 矢印には動作を表す動詞でラベルを付ける - 「メールを送信する」「読み取る」など、単なる「使用する」は避ける
4. テクノロジーのラベルを含める - 「JSON/HTTPS」「JDBC」「gRPC」など
5. 1つの図につき要素は20個未満にする - 複雑なシステムは複数の図に分割する

明確さのためのガイドライン

1. レベル 1 から始める - Context 図はシステムの範囲を捉えるのに役立つ
2. 1ファイルに1つの図 - 図は単一の抽象度に絞って作成する
3. 意味のあるエイリアスを使う - 説明的なエイリアスを使用する（例: s1 ではなく orderService）
4. 説明文は簡潔に - 可能な限り説明文は50文字以内にする
5. 必ずタイトルを付ける - 「[システム名] のシステムコンテキスト図」

避けるべきこと

詳細なアンチパターンについては 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 - マイクロサービス、イベント駆動、デプロイメント