ストーリー

設計ドキュメントの構造

interface DesignDocument {
  // 1. 概要
  overview: {
    purpose: string;      // このドキュメントの目的
    scope: string;        // 対象範囲
    audience: string[];   // 想定読者
    relatedDocs: string[]; // 関連ドキュメント（RFC、ADR等）
  };

  // 2. システム設計
  systemDesign: {
    architecture: string;     // アーキテクチャ概要
    components: Component[];  // コンポーネント一覧
    dataFlow: string;         // データの流れ
    apiDesign: APISpec[];     // API仕様
  };

  // 3. データ設計
  dataDesign: {
    dataModel: string;        // データモデル
    storageStrategy: string;  // 保存戦略
    migration: string;        // マイグレーション計画
  };

  // 4. 運用設計
  operationalDesign: {
    monitoring: string;       // 監視計画
    logging: string;          // ログ戦略
    alerting: string;         // アラート設定
    rollback: string;         // ロールバック手順
  };

  // 5. テスト計画
  testPlan: {
    strategy: string;
    coverage: string;
    environments: string[];
  };
}

interface Component {
  name: string;
  responsibility: string;
  technology: string;
  interfaces: string[];
}

interface APISpec {
  method: string;
  path: string;
  description: string;
  requestBody?: string;
  responseBody: string;
}

設計ドキュメントの実例

# 設計ドキュメント: 商品検索サービス

## 1. 概要

### 目的
商品検索機能をElasticsearchベースのマイクロサービスとして実装する。

### 対象範囲
- 商品の全文検索API
- ファセット検索（カテゴリ、価格帯）
- インデックス同期の仕組み
- 対象外: 管理画面UI、レコメンデーション

### 想定読者
- バックエンド開発チーム
- SREチーム
- フロントエンド開発チーム（API仕様の部分）

## 2. アーキテクチャ

### コンポーネント構成

┌──────────┐    ┌──────────────┐    ┌───────────────┐
│ Frontend │───→│ Search API   │───→│ Elasticsearch │
│          │    │ (NestJS)     │    │               │
└──────────┘    └──────────────┘    └───────────────┘
                                           ↑
                ┌──────────────┐    ┌──────┴────────┐
                │  Admin API   │───→│  PostgreSQL   │
                │  (Rails)     │    │  (Source)     │
                └──────────────┘    └──────┬────────┘
                                           │
                                    ┌──────┴────────┐
                                    │  CDC Worker   │
                                    │  (同期処理)    │
                                    └───────────────┘

### コンポーネント詳細

| コンポーネント | 責務 | 技術 |
|--------------|------|------|
| Search API | 検索クエリの処理、結果の整形 | NestJS + TypeScript |
| Elasticsearch | 全文検索インデックス | Elasticsearch 8.x |
| CDC Worker | PostgreSQL → ES のデータ同期 | Node.js + Debezium |
| PostgreSQL | 商品データのSource of Truth | PostgreSQL 16 |

## 3. API設計

### GET /api/v1/products/search
商品を検索する。

**リクエスト:**
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| q | string | No | 検索キーワード |
| category | string | No | カテゴリID |
| priceMin | number | No | 最低価格 |
| priceMax | number | No | 最高価格 |
| page | number | No | ページ番号（デフォルト: 1） |
| limit | number | No | 件数（デフォルト: 20, 最大: 100） |

**レスポンス:**

interface SearchResponse {
  data: Product[];
  pagination: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
  };
  facets: {
    categories: Array<{ id: string; name: string; count: number }>;
    priceRanges: Array<{ min: number; max: number; count: number }>;
  };
  meta: {
    took: number; // 検索にかかった時間（ms）
  };
}

図の描き方

設計ドキュメントでは、テキストだけでなく図も重要です。

## 推奨ツール

| ツール | 用途 | 特徴 |
|--------|------|------|
| Mermaid | シーケンス図、フロー図 | Markdown内に記述可能 |
| PlantUML | クラス図、コンポーネント図 | テキストベース |
| draw.io | 自由なダイアグラム | GUI操作 |
| Excalidraw | ラフスケッチ | 手書き風 |

## Mermaid の例（シーケンス図）

sequenceDiagram
    participant C as Client
    participant A as Search API
    participant E as Elasticsearch
    participant P as PostgreSQL

    C->>A: GET /products/search?q=laptop
    A->>E: Search query
    E-->>A: Search results
    A-->>C: Formatted response

    Note over P,E: CDC による非同期同期
    P->>E: Index update (via CDC Worker)

良い設計ドキュメントの特徴

まとめ

チェックリスト

• 設計ドキュメントの構成要素を理解した
• API設計の記述方法を学んだ
• 図の描き方とツールを把握した
• 良い設計ドキュメントの特徴を理解した

次のステップへ

次は「レビュープロセスの構築」を学びます。書かれたドキュメントを効果的にレビューし、品質を高める仕組みを作りましょう。

推定読了時間: 30分