PART 02 — アーキテクチャ設計標準とAPI設計ガイドライン
レイヤー構成・ADR・エンドポイント命名・レスポンス形式の統一

src/
  domain/          # ビジネスロジック・エンティティ（外部依存なし）
    user/
      User.ts      # エンティティ（IDと属性のみ。DBやAPIを知らない）
      UserRepository.ts  # リポジトリインターフェース（実装はinfraに）
  application/     # ユースケース（domainに依存してよい。インフラには依存しない）
    user/
      CreateUserUseCase.ts
      GetUserUseCase.ts
  infrastructure/  # DB・外部API実装（domain/applicationに依存してよい）
    database/
      UserRepositoryImpl.ts   # UserRepositoryの実装
    external/
      MailService.ts          # 外部メールAPIのラッパー
  presentation/    # コントローラ・ルーティング（applicationに依存してよい）
    api/
      UserController.ts
      UserRouter.ts

# ADR-001: データベースにPostgreSQLを採用する

## ステータス
採用済み（2024-03-01）

## コンテキスト
サービス開始時のデータ量は小規模だが、将来的にJSONデータの柔軟なクエリが
必要になる見込み。チームの既存スキルセットはMySQL寄りだが、柔軟性を優先する。

## 検討した選択肢
1. MySQL: チームの習熟度が高い。JSON対応はMySQL 5.7以降で可能だが限定的
2. PostgreSQL: JSONB型によるインデックス付き高速JSON検索が可能。拡張機能が豊富
3. MongoDB: JSON-nativeだがトランザクション管理が複雑になる

## 決定
PostgreSQLを採用する。JSONB型の豊富なサポートと、
スケーラビリティの実績が決め手。

## 結果
- メリット: JSONB型による柔軟なクエリ、豊富なエコシステム、ACID準拠
- デメリット: MySQLより運用知識のあるメンバーが少ない → 学習コストが発生
- フォローアップ: 2024-06-01までにチーム全員がPostgreSQL基礎研修を受講する

GET  /getUser?id=123        # クエリパラメータでID指定
GET  /articles/456          # パスパラメータでID指定
POST /create-comment        # 動詞を含むエンドポイント名
DELETE /api/v1/users/789    # バージョニングあり
POST /updateProfile         # PATCHで行うべき操作をPOSTで

{
  "data": {
    "id": 123,
    "name": "山田太郎",
    "email": "yamada@example.com"
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

{
  "error": {
    "code": "USER_NOT_FOUND",
    "message": "指定されたユーザーが見つかりません",
    "detail": {
      "user_id": 123
    }
  },
  "meta": {
    "request_id": "req_abc123"
  }
}

# offset-based（シンプルだが大量データで遅くなる）
GET /articles?page=3&per_page=20

# cursor-based（大量データでも高速、無限スクロールに向く）
GET /articles?cursor=eyJpZCI6MTIzfQ&limit=20

# cursor-basedのレスポンス例
{
  "data": [...],
  "pagination": {
    "next_cursor": "eyJpZCI6MTQzfQ",
    "has_next": true,
    "total": null  # cursor-basedでは総件数を返さない（パフォーマンスのため）
  }
}