# インフラ設計書

## 概要

本ドキュメントは、Giselle（AIワークフロー設計・実行プラットフォーム）のインフラストラクチャ構成を定義する。GiselleはVercelプラットフォーム上でホストされるサーバーレスアーキテクチャを採用し、外部マネージドサービスと連携してスケーラブルかつ高可用性なシステムを実現している。

## システム構成

### 全体構成

Giselleは以下のコンポーネントで構成されるサーバーレスアーキテクチャを採用している。

1. **アプリケーション層**: Vercel上でホストされるNext.js 16アプリケーション（App Router）
2. **データベース層**: Vercel Postgres（PostgreSQL）+ pgvector拡張
3. **ストレージ層**: Supabase Storage（S3互換）
4. **認証層**: Supabase Auth
5. **バックグラウンドジョブ層**: Trigger.dev
6. **外部AI/ML層**: OpenAI API、Google Vertex AI、Anthropic等のLLMプロバイダー
7. **決済層**: Stripe
8. **監視層**: Sentry、Langfuse

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| Vercel Edge Functions | APIルート、SSR | サーバーレス（自動スケール） | 自動 |
| Vercel Serverless Functions | 長時間実行タスク、バックグラウンド処理 | サーバーレス（自動スケール） | 自動 |
| Vercel Postgres | データベース | マネージドPostgreSQL | 1（レプリカ自動） |
| Supabase Storage | ファイルストレージ | S3互換オブジェクトストレージ | マネージド |
| Trigger.dev | バックグラウンドジョブ実行 | サーバーレス（最大6時間実行） | 自動 |

### ネットワーク構成

- **CDN**: Vercel Edge Network（グローバルCDN）
- **DNS**: Vercel DNS管理
- **SSL/TLS**: Vercel自動発行・更新（Let's Encrypt）
- **リージョン**: グローバル分散（Vercel Edge）

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Next.js | 16.x | Webアプリケーションフレームワーク |
| Node.js | 24.x | ランタイム |
| Drizzle ORM | 0.44.x | データベースORM |
| pgvector | 0.2.x | ベクトル検索拡張 |
| Supabase Auth | 2.50.x | 認証・認可 |
| Trigger.dev SDK | 4.3.x | バックグラウンドジョブ |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| Vercel Postgres | メインデータベース | 接続プール経由（POSTGRES_URL） |
| Supabase | 認証、ストレージ | REST API / SDK |
| OpenAI API | テキスト生成、エンベディング | REST API |
| Google Vertex AI | LLMプロバイダー | REST API |
| Anthropic | LLMプロバイダー | REST API |
| Stripe | 決済処理、サブスクリプション管理 | REST API / Webhook |
| GitHub | OAuth認証、リポジトリ連携 | REST API / GraphQL / Webhook |
| Sentry | エラー監視 | SDK |
| Langfuse | LLMトレーシング | SDK |
| Google Tag Manager | アナリティクス | クライアントサイドSDK |

## スケーリング設計

### 水平スケーリング

- **Vercel Functions**: リクエストに応じて自動スケール
- **Edge Functions**: グローバルに分散し、ユーザーに近いエッジで実行
- **Trigger.dev**: ジョブキューベースの自動スケーリング

### 垂直スケーリング

- **Vercel Postgres**: プランに応じたリソース調整
- **Supabase Storage**: 使用量に応じた自動スケール

### スケーリングトリガー

| コンポーネント | トリガー | 最大値 |
| --- | --- | --- |
| Serverless Functions | 同時リクエスト数 | プラン依存 |
| Edge Functions | リクエストレート | 無制限（レート制限あり） |
| Trigger.dev Jobs | キュー長 | 最大6時間/ジョブ |

## 可用性設計

### 冗長構成

- **Vercel**: 複数リージョンへの自動フェイルオーバー
- **Vercel Postgres**: 自動バックアップ、ポイントインタイムリカバリ
- **Supabase**: マルチリージョン対応（プラン依存）

### フェイルオーバー方式

- **CDN**: 自動フェイルオーバー（Vercel Edge Network）
- **データベース**: 自動フェイルオーバー（Vercel Postgres）
- **アプリケーション**: Vercelによる自動デプロイ・ロールバック

### SLA目標

| コンポーネント | 目標稼働率 |
| --- | --- |
| アプリケーション（Vercel） | 99.99% |
| データベース（Vercel Postgres） | 99.95% |
| ストレージ（Supabase） | 99.9% |

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| Vercel Postgres | 自動スナップショット | 継続的 | プラン依存（7日以上） |
| Supabase Storage | オブジェクトバージョニング | リアルタイム | プラン依存 |
| ソースコード | Git（GitHub） | コミット毎 | 無期限 |

## 監視設計

### エラー監視

- **Sentry**: アプリケーションエラー、例外のリアルタイム監視
  - Server/Edge両ランタイムに対応
  - ソースマップアップロードによる詳細なスタックトレース
  - Vercel Cron Monitorsとの連携

### LLMトレーシング

- **Langfuse**: LLM呼び出しのトレース、コスト追跡
  - 生成リクエストのメタデータ記録
  - チーム・プラン別のタグ付け

### パフォーマンス監視

- **Vercel Analytics**: リアルユーザーモニタリング（RUM）
- **Vercel Speed Insights**: Core Web Vitals監視

### 定期実行タスク（Cron Jobs）

| タスク | スケジュール | 目的 |
| --- | --- | --- |
| GitHub Ingest | 10分毎 | GitHubリポジトリのベクトルインデックス更新 |
| Document Ingest | 3分毎 | ドキュメントのベクトルインデックス更新 |

## セキュリティ設計

### HTTPセキュリティヘッダー

```
X-Frame-Options: DENY
X-DNS-Prefetch-Control: on
X-XSS-Protection: 1; mode=block
X-Content-Type-Options: nosniff
Referrer-Policy: origin-when-cross-origin
```

### 認証・認可

- **Supabase Auth**: OAuth（GitHub、Google）、メール認証
- **セッション管理**: 署名付きCookie（COOKIE_SECRET）
- **トークン暗号化**: AES-256-GCM（TOKEN_ENCRYPTION_KEY）

### API セキュリティ

- **APIキー**: scrypt KDF によるハッシュ化
- **レート制限**: チーム・ルート単位のカウンターベース制限

## 環境変数管理

### 必須環境変数

| 変数名 | 用途 |
| --- | --- |
| COOKIE_SECRET | Cookie署名 |
| TOKEN_ENCRYPTION_KEY | OAuthトークン暗号化 |
| POSTGRES_URL | データベース接続 |
| NEXT_PUBLIC_SUPABASE_URL | Supabase接続 |
| NEXT_PUBLIC_SUPABASE_ANON_KEY | Supabaseクライアント認証 |
| OPENAI_API_KEY | OpenAI API認証 |
| STRIPE_SECRET_KEY | Stripe API認証 |

### 環境変数管理方式

- **本番環境**: Vercel Environment Variables + Edge Config
- **開発環境**: `.env.local`ファイル

## 備考

### デプロイメント

- **CI/CD**: Vercel自動デプロイ（GitHub連携）
- **プレビュー環境**: PR毎の自動プレビューデプロイ
- **本番デプロイ**: mainブランチへのマージで自動デプロイ

### 依存関係管理

- **パッケージマネージャ**: pnpm 10.x
- **モノレポ管理**: Turborepo
- **依存関係バージョン管理**: pnpm catalog方式

### ランタイム要件

- **Node.js**: 24.x以上
- **対応ブラウザ**: 最新のモダンブラウザ
