# インフラ設計書

## 概要

本ドキュメントは、Decap CMS（旧 Netlify CMS）のインフラストラクチャ構成を記載する。Decap CMS はオープンソースの Git ベース ヘッドレス CMS であり、クライアントサイド SPA としてブラウザ上で動作する。バックエンドストレージには各種 Git ホスティングサービス（GitHub、GitLab、Bitbucket、Azure DevOps、Gitea）を利用し、ローカル開発用には Express.js ベースのプロキシサーバー（decap-server）を提供する。

## システム構成

### 全体構成

Decap CMS は以下の特徴を持つアーキテクチャで構成される。

- **クライアントサイド SPA**: ブラウザ上で動作する React アプリケーション。サーバーサイドレンダリングは不要
- **Git ベースバックエンド**: コンテンツは Git リポジトリに直接保存される。専用のデータベースサーバーは不要
- **静的サイトホスティング**: Netlify 等の静的サイトホスティングサービスでデプロイ
- **モノレポ構成**: Lerna + Nx によるモノレポで 38 以上のパッケージを管理

### サーバー構成

| サーバー種別 | 役割 | 技術スタック | 備考 |
| --- | --- | --- | --- |
| 静的ホスティング（本番） | CMS SPA の配信 | Netlify | netlify.toml で設定。Yarn 1.22.4 + frozen-lockfile |
| ローカル開発サーバー | 開発時の CMS 配信 | webpack-dev-server | ポート 8080 で http-server 起動 |
| プロキシサーバー（decap-server） | ローカル開発時の Git/FS 操作 | Express.js (Node.js) | ポート 8081（デフォルト）。fs モード / git モード切替可能 |
| CI/CD ランナー | テスト・ビルド・パブリッシュ | GitHub Actions | ubuntu-latest / macos-latest / windows-latest |

### ネットワーク構成

Decap CMS はクライアントサイドアプリケーションのため、専用のネットワークインフラは不要。以下のネットワーク通信が発生する。

| 通信元 | 通信先 | プロトコル | 用途 |
| --- | --- | --- | --- |
| ブラウザ (CMS SPA) | GitHub API | HTTPS (GraphQL / REST) | コンテンツ CRUD 操作 |
| ブラウザ (CMS SPA) | GitLab API | HTTPS (GraphQL / REST) | コンテンツ CRUD 操作 |
| ブラウザ (CMS SPA) | Bitbucket API | HTTPS (REST) | コンテンツ CRUD 操作 |
| ブラウザ (CMS SPA) | Azure DevOps API | HTTPS (REST) | コンテンツ CRUD 操作 |
| ブラウザ (CMS SPA) | Gitea API | HTTPS (REST) | コンテンツ CRUD 操作 |
| ブラウザ (CMS SPA) | Netlify Identity | HTTPS | 認証（/.netlify/identity） |
| ブラウザ (CMS SPA) | Netlify Git Gateway | HTTPS | Git 操作プロキシ（/.netlify/git） |
| ブラウザ (CMS SPA) | decap-server (localhost) | HTTP | ローカル開発時のプロキシ通信 |
| ブラウザ (CMS SPA) | Cloudinary CDN | HTTPS | メディアライブラリ連携 |
| ブラウザ (CMS SPA) | Uploadcare CDN | HTTPS | メディアライブラリ連携 |
| ブラウザ (CMS SPA) | AWS Cognito | HTTPS | AWS Cognito 認証 |

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Express.js | ^4.18.2 | decap-server の HTTP サーバーフレームワーク |
| cors | ^2.8.5 | decap-server の CORS 処理 |
| morgan | ^1.9.1 | decap-server の HTTP リクエストログ |
| winston | ^3.3.3 | decap-server のロギング |
| simple-git | ^3.0.0 | decap-server の Git 操作 |
| @hapi/joi | ^17.0.2 | decap-server のリクエストバリデーション |
| async-mutex | ^0.3.0 | decap-server の非同期ロック制御 |
| webpack | ^5.75.0 | フロントエンド・サーバーバンドリング |
| webpack-dev-server | ^5.2.2 | 開発用ローカルサーバー |
| Babel | ^7.23.9 | JavaScript / TypeScript トランスパイル |
| TypeScript | ^4.9.4 | 型チェック |
| Nx | ^21.1.0 | モノレポタスクランナー・キャッシング |
| Lerna | ^8.0.2 | モノレポパッケージ管理・バージョニング |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| GitHub | コンテンツリポジトリ（GraphQL API + REST API） | OAuth2 (PKCE / Implicit / Netlify Auth) |
| GitLab | コンテンツリポジトリ（GraphQL API + REST API） | OAuth2 (PKCE / Implicit) |
| Bitbucket | コンテンツリポジトリ（REST API） | OAuth2 (Implicit) |
| Azure DevOps | コンテンツリポジトリ（REST API） | OAuth2 |
| Gitea | コンテンツリポジトリ（REST API） | OAuth2 |
| Netlify Identity | ユーザー認証（GoTrue ベース） | HTTPS (JWT) |
| Netlify Git Gateway | Git 操作プロキシ | HTTPS |
| Netlify Large Media | 大容量ファイル管理（Git LFS） | HTTPS |
| AWS Cognito | ユーザー認証（GitHub プロキシ経由） | HTTPS (OAuth2) |
| Cloudinary | メディアライブラリ（画像・動画管理） | JavaScript SDK（CDN 経由ロード） |
| Uploadcare | メディアライブラリ（ファイルアップロード） | JavaScript SDK（CDN 経由ロード） |
| npm Registry | パッケージ配布 | HTTPS (OIDC Trusted Publishers) |
| Slack | リリース通知・オンデマンドパブリッシュトリガー | Webhook |

## スケーリング設計

Decap CMS はクライアントサイド SPA であるため、サーバーサイドのスケーリングは基本的に不要。

| 項目 | 方式 | 説明 |
| --- | --- | --- |
| フロントエンド配信 | CDN (Netlify) | Netlify の CDN エッジネットワークにより自動スケーリング |
| バックエンド API | 外部サービス依存 | GitHub / GitLab 等の各 Git ホスティングサービスのスケーリングに依存 |
| CI/CD | GitHub Actions 並列化 | E2E テストは 4 台のマシンで並列実行。マトリクスビルドで複数 OS・Node.js バージョンに対応 |
| ビルドキャッシュ | Nx キャッシュ | `.nx/cache` ディレクトリでタスク実行結果をキャッシュし、CI の再実行を高速化 |

## 可用性設計

| 項目 | 方式 | 説明 |
| --- | --- | --- |
| フロントエンド | Netlify CDN | グローバル CDN による高可用性。静的ファイル配信のため単一障害点なし |
| コンテンツバックエンド | Git ホスティングサービスの SLA に依存 | GitHub (99.9%)、GitLab 等のサービス可用性に準拠 |
| 認証 | 複数認証方式のフォールバック | Netlify Identity、PKCE OAuth、Implicit OAuth の 3 方式を提供 |
| ローカル開発 | decap-server | オフラインでもローカルファイルシステムモードで開発可能 |

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| コンテンツデータ | Git リポジトリ（分散 VCS） | コミット毎 | Git 履歴として永続保持 |
| メディアファイル | Git リポジトリ または Cloudinary/Uploadcare | コミット毎 / アップロード毎 | サービスのポリシーに準拠 |
| CMS 設定 (config.yml) | Git リポジトリ | コミット毎 | Git 履歴として永続保持 |
| npm パッケージ | npm Registry | リリース毎 | npm のポリシーに準拠 |

## 監視設計

| 項目 | 方式 | 説明 |
| --- | --- | --- |
| CI/CD パイプライン | GitHub Actions ステータス | プッシュ / PR 時に自動実行。ユニットテスト、型チェック、lint、E2E テストの成否を監視 |
| ローカルサーバーログ | winston + morgan | decap-server で HTTP リクエストログとアプリケーションログを出力。ログレベルは環境変数 `LOG_LEVEL` で制御 |
| ビルドステータス | Netlify ビルドログ | Netlify デプロイ時のビルド成否を監視 |
| パッケージ公開 | GitHub Actions publish ワークフロー | タグプッシュ時の npm パブリッシュ成否を監視。OIDC Trusted Publishers による認証 |
| リリース通知 | Slack Webhook | `functions/publish.js` による Slack 通知。許可ユーザーのみオンデマンドパブリッシュ可能 |

## CI/CD パイプライン

### テスト・ビルド（`.github/workflows/nodejs.yml`）

| ステージ | 実行条件 | 内容 |
| --- | --- | --- |
| changes | push (main/master) / PR | パス変更検出（website/ を除外） |
| build-unit | changes で CMS 変更あり | lint、型チェック、ユニットテスト。マトリクス: ubuntu/macos/windows × Node.js 22.x/24.x |
| e2e | changes で CMS 変更あり | E2E テスト (Cypress)。4 マシン並列実行。Nx キャッシュ利用 |

### パブリッシュ（`.github/workflows/publish.yml`）

| ステージ | 実行条件 | 内容 |
| --- | --- | --- |
| publish | タグ `decap-*@*` プッシュ | ビルド → テスト → npm publish (Lerna)。OIDC Trusted Publishers で認証 |

### リリース作成（`.github/workflows/create-release.yml`）

| ステージ | 実行条件 | 内容 |
| --- | --- | --- |
| create-release | タグ `decap-cms@*` 作成 | GitHub Release を自動作成 |

## 開発環境

| 項目 | 内容 |
| --- | --- |
| パッケージマネージャ | npm（ワークスペース機能利用） |
| モノレポ管理 | Lerna（independent versioning） + Nx |
| バージョニング | Conventional Commits ベース |
| ブランチ戦略 | main / release/* からのみバージョン作成可能 |
| 開発サーバー | webpack-dev-server (ポート 8080) + decap-server (ポート 8081) |
| テストフレームワーク | Jest（ユニット）、Cypress（E2E） |
| コード品質 | ESLint、Prettier、Stylelint、commitlint |
| Git フック | Husky（pre-commit） |

## 備考

- Decap CMS はクライアントサイド SPA として設計されており、従来のサーバー・DB 構成とは異なるアーキテクチャを採用している
- コンテンツの永続化は Git リポジトリに依存しており、専用のデータベースは不要
- decap-server はローカル開発専用であり、本番環境では使用しない
- 認証は Git ホスティングサービスの OAuth2、Netlify Identity、AWS Cognito の 3 系統を提供
- メディア管理は Git リポジトリへの直接保存の他、Cloudinary / Uploadcare との外部連携をサポート
- npm パッケージの公開には OIDC Trusted Publishers を使用し、npm トークンの静的管理を不要としている
