# アーキテクチャ設計書

## 概要

本ドキュメントは、Payload CMS（バージョン3.x）のアーキテクチャ設計について記述する。PayloadはNext.jsネイティブなヘッドレスCMSであり、モノレポ構成で開発されている。コアCMSプラットフォーム、データベースアダプター、プラグイン、UIコンポーネント、およびツールを含む包括的なシステムである。

## システム全体構成

### アーキテクチャ概要図

[アーキテクチャ構成図.md](./アーキテクチャ構成図.md)を参照。

### システム境界と外部連携

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| MongoDB | Mongoose ODM | ドキュメント型データベース（プライマリDB選択肢） |
| PostgreSQL | Drizzle ORM | リレーショナルデータベース（プライマリDB選択肢） |
| SQLite | Drizzle ORM | 軽量リレーショナルデータベース |
| Redis | ioredis | キャッシュ・KVストア |
| Amazon S3 | AWS SDK | ファイルストレージ |
| Azure Blob Storage | Azure SDK | ファイルストレージ |
| Google Cloud Storage | GCS SDK | ファイルストレージ |
| Vercel Blob | Vercel SDK | ファイルストレージ |
| Cloudflare R2 | AWS S3互換SDK | ファイルストレージ |
| Nodemailer | SMTP | メール送信 |
| Resend | REST API | メール送信 |
| Stripe | REST API | 決済処理（プラグイン経由） |
| Sentry | Sentry SDK | エラー監視（プラグイン経由） |

## レイヤー構成

### アーキテクチャスタイル

プラグインアーキテクチャ / アダプターパターン / モノレポ構成

Payload CMSはプラグインベースの拡張可能なアーキテクチャを採用している。コアパッケージ（`payload`）が中心となり、各種アダプター（データベース、ストレージ、メール）およびプラグインが機能を拡張する構成である。Next.js統合レイヤーを通じてフルスタックアプリケーションとして動作する。

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Presentation | 管理UIの提供、React Server Components | `@payloadcms/ui`, `@payloadcms/next` |
| Application | ビジネスロジック、CRUD操作、認証・認可 | `payload`（コアパッケージ） |
| API | REST/GraphQL API提供 | `@payloadcms/graphql`, `@payloadcms/next/routes` |
| Data Access | データベース抽象化、ストレージ抽象化 | `@payloadcms/db-*`, `@payloadcms/drizzle`, `@payloadcms/storage-*` |
| Infrastructure | 外部サービス統合、メール、KVストア | `@payloadcms/email-*`, `@payloadcms/kv-redis` |

### レイヤー間の依存関係ルール

- **依存の方向性**: 上位レイヤーから下位レイヤーへの依存のみ許可
- **許可される参照**:
  - Presentationレイヤー → Application, APIレイヤー
  - Applicationレイヤー → Data Access, Infrastructureレイヤー
  - 全レイヤー → `payload`コアパッケージの型定義
- **禁止される参照**:
  - 下位レイヤーから上位レイヤーへの直接参照
  - プラグイン間の相互依存（疎結合を維持）

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| Core | CMS基盤機能、設定管理、型システム | `packages/payload` |
| Admin UI | 管理画面UI、フォーム、フィールド | `packages/ui` |
| Next.js Integration | Next.js統合、ルーティング、SSR/RSC | `packages/next` |
| Database | データ永続化抽象化 | `packages/db-*`, `packages/drizzle` |
| Storage | ファイルストレージ抽象化 | `packages/storage-*`, `packages/plugin-cloud-storage` |
| Rich Text | リッチテキストエディタ | `packages/richtext-lexical`, `packages/richtext-slate` |
| API | REST/GraphQL API | `packages/graphql` |
| Authentication | 認証・認可 | `packages/payload/src/auth` |
| Plugins | 拡張機能 | `packages/plugin-*` |
| i18n | 国際化 | `packages/translations` |

### パッケージ構造

```
packages/
├── payload/                    # コアCMSパッケージ
│   └── src/
│       ├── admin/              # 管理UI関連ロジック
│       ├── auth/               # 認証・認可
│       │   ├── baseFields/     # 認証用基本フィールド
│       │   ├── endpoints/      # 認証API
│       │   ├── operations/     # 認証操作
│       │   └── strategies/     # 認証ストラテジー（JWT, API Key）
│       ├── collections/        # コレクション定義・操作
│       ├── config/             # 設定管理
│       ├── database/           # DB抽象レイヤー
│       ├── email/              # メール抽象レイヤー
│       ├── errors/             # エラー定義
│       ├── fields/             # フィールド定義
│       ├── globals/            # グローバル設定
│       ├── queues/             # ジョブキュー
│       ├── uploads/            # ファイルアップロード
│       ├── utilities/          # ユーティリティ
│       └── versions/           # バージョン管理
├── ui/                         # 管理UI (React Server Components)
│   └── src/
│       ├── elements/           # UIコンポーネント
│       ├── fields/             # フィールドコンポーネント
│       ├── forms/              # フォーム関連
│       ├── hooks/              # React Hooks
│       ├── icons/              # アイコン
│       ├── providers/          # Context Providers
│       └── views/              # ビューコンポーネント
├── next/                       # Next.js統合レイヤー
│   └── src/
│       ├── auth/               # 認証ユーティリティ
│       ├── layouts/            # レイアウト
│       ├── routes/             # ルートハンドラー
│       ├── views/              # ビュー
│       └── withPayload/        # Next.js設定統合
├── db-mongodb/                 # MongoDB アダプター
├── db-postgres/                # PostgreSQL アダプター
├── db-sqlite/                  # SQLite アダプター
├── db-vercel-postgres/         # Vercel Postgres アダプター
├── db-d1-sqlite/               # Cloudflare D1 アダプター
├── drizzle/                    # Drizzle ORM 共通レイヤー
├── graphql/                    # GraphQL API
├── richtext-lexical/           # Lexical リッチテキスト
├── richtext-slate/             # Slate リッチテキスト
├── storage-s3/                 # S3 ストレージ
├── storage-azure/              # Azure ストレージ
├── storage-gcs/                # GCS ストレージ
├── storage-vercel-blob/        # Vercel Blob ストレージ
├── storage-r2/                 # Cloudflare R2 ストレージ
├── storage-uploadthing/        # Uploadthing ストレージ
├── email-nodemailer/           # Nodemailer アダプター
├── email-resend/               # Resend アダプター
├── kv-redis/                   # Redis KV アダプター
├── translations/               # 国際化翻訳
├── plugin-*/                   # 各種プラグイン
└── create-payload-app/         # CLIツール
```

### コンポーネント依存関係

主要コンポーネント間の依存関係は以下の通りである：

1. **payload（コア）** - 全パッケージの基盤
2. **@payloadcms/ui** → payload（型定義・ユーティリティ）
3. **@payloadcms/next** → payload, @payloadcms/ui, @payloadcms/graphql
4. **@payloadcms/db-*** → payload（BaseDatabaseAdapterインターフェース実装）
5. **@payloadcms/drizzle** → payload（Drizzle ORMベースアダプター共通）
6. **@payloadcms/db-postgres/sqlite** → @payloadcms/drizzle
7. **@payloadcms/storage-*** → @payloadcms/plugin-cloud-storage
8. **@payloadcms/plugin-*** → payload（Plugin型に準拠）

## ミドルウェア構成

### データベース

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| NoSQL | MongoDB (Mongoose) | 8.15.1 | ドキュメント型データ保存（デフォルト） |
| RDB | PostgreSQL (Drizzle ORM) | 0.44.7 | リレーショナルデータ保存 |
| RDB | SQLite (Drizzle ORM) | 0.44.7 | 軽量ローカルデータベース |
| RDB | Vercel Postgres | - | Vercel環境用PostgreSQL |
| RDB | Cloudflare D1 | - | Cloudflare Workers用SQLite |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| Redis (ioredis) | ^5.4.1 | KVストア、セッション管理 | 設定により可変 |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Croner | 9.1.0 | スケジュールジョブ（組み込み） |
| Jobs Queue | - | バックグラウンドジョブ処理（組み込み） |

### 検索エンジン

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| - | - | データベースネイティブ検索を使用 |

### その他ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| sharp | 0.32.6 | 画像処理・リサイズ |
| pino | 9.14.0 | ロギング |
| jose | 5.9.6 | JWT処理 |
| ws | ^8.16.0 | WebSocket通信 |

## データフロー

### リクエスト処理の流れ

1. **クライアントリクエスト受信**: Next.jsアプリケーションがHTTPリクエストを受信
2. **ルーティング**: `@payloadcms/next/routes`によりAPI/管理画面ルートを判定
3. **認証・認可**: JWT/API Key認証戦略による認証、アクセス制御チェック
4. **リクエスト処理**: コアパッケージのオペレーション（`find`, `create`, `update`, `delete`）実行
5. **データベースアクセス**: 該当するDBアダプター経由でデータ操作
6. **フック実行**: beforeChange, afterChange等のフック処理
7. **レスポンス生成**: JSON/HTML（管理UI）レスポンスを返却

### 非同期処理の流れ

1. **ジョブ登録**: `payload.jobs`を通じてジョブをキューに登録
2. **スケジュール管理**: Cronerによるスケジュール管理
3. **ジョブ実行**: バックグラウンドワーカーによるジョブ処理
4. **結果保存**: ジョブ結果をデータベースに保存
5. **通知**: 必要に応じてWebhook/メール通知

### データ永続化の流れ

1. **入力バリデーション**: フィールド定義に基づく入力検証
2. **フック実行**: `beforeValidate`, `beforeChange`フック
3. **データ変換**: フィールドタイプに応じたデータ変換
4. **DBアダプター呼び出し**: 抽象化されたDBアダプターインターフェース経由
5. **トランザクション管理**: アダプター固有のトランザクション処理
6. **バージョン保存**: バージョン管理有効時は履歴保存
7. **フック実行**: `afterChange`フック

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| JWT認証 | `packages/payload/src/auth/strategies/jwt.ts` | ユーザー認証（デフォルト） |
| API Key認証 | `packages/payload/src/auth/strategies/apiKey.ts` | プログラマティックアクセス |
| Session管理 | `packages/payload/src/auth/sessions.ts` | セッション有効期限管理 |
| アクセス制御 | `packages/payload/src/auth/executeAccess.ts` | フィールド/コレクション/グローバルレベルアクセス制御 |
| パーミッション | `packages/payload/src/auth/types.ts` | CRUD操作権限、フィールド権限 |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | Pino ロガー | stdout/ファイル（設定可能） |
| 監査ログ | バージョン管理機能 | データベース（versionsコレクション） |
| アクセスログ | Next.jsミドルウェア | stdout |

### エラーハンドリング

エラーハンドリングは`packages/payload/src/errors/`で定義されたカスタムエラークラスにより実装されている。

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| ValidationError | フィールドバリデーション失敗 | 400 Bad Request + フィールドエラー詳細 |
| NotFound | リソース未発見 | 404 Not Found |
| Forbidden | アクセス権限不足 | 403 Forbidden |
| Unauthorized | 認証失敗 | 401 Unauthorized |
| APIError | 一般APIエラー | 500 Internal Server Error |
| DatabaseError | DB操作エラー | 500 + エラー詳細（開発モード） |

### トランザクション管理

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| 単一操作 | DBアダプター自動管理 | アダプター依存 |
| 複数操作 | `payload.db.beginTransaction()` | READ COMMITTED（PostgreSQL） |
| バルク操作 | `bulkOperationsSingleTransaction`フラグ | 設定可能 |

## 設計原則・コーディング規約

### 適用している設計原則

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| アダプターパターン | データベース、ストレージ、メール | `BaseDatabaseAdapter`インターフェース |
| プラグインアーキテクチャ | 機能拡張 | `Plugin`型による設定拡張 |
| 依存性注入 | 設定オブジェクト | `payload.init(config)`による設定注入 |
| 単一責任原則 | パッケージ分割 | 各アダプターが1つの責務を持つ |
| 関数優先 | ユーティリティ | クラスより関数を優先 |

### コーディング規約

- **パラメータ**: 単一オブジェクトパラメータを優先（後方互換性確保）
- **型定義**: interfaceよりtypeを優先（外部型の拡張時を除く）
- **関数**: classより関数を優先（エラークラス/アダプターを除く）
- **純粋関数**: 可能な限り純粋関数を使用、副作用時は変更後オブジェクトを返却
- **インポート**: 型は`import type`、値は通常の`import`を分離
- **命名規則**: boolean変数は`is`/`has`/`can`/`should`プレフィックス
- **ロガー使用**: `payload.logger.error({ msg: '...', err: error })`形式

## 備考

- Payload 3.xはNext.js 15/16をサポートし、App Router内にインストールされる
- React Server Components（RSC）を活用した管理UI
- TypeScript厳格モードでの開発
- pnpmワークスペースとTurboによるモノレポ管理
- Node.js ^18.20.2 || >=20.9.0が必要
