# インフラ設計書

## 概要

本ドキュメントは、LIAM (Lightweight Integration Architecture Manager) プロジェクトのインフラストラクチャ設計を記載する。本プロジェクトは、ERD (Entity Relationship Diagram) 可視化ツールを提供するWebアプリケーションであり、Vercel上にホスティングされ、Supabaseをバックエンドサービスとして利用するサーバーレスアーキテクチャを採用している。

## システム構成

### 全体構成

本システムはモノレポ構成を採用し、pnpm workspacesとTurborepoによるビルド管理を行っている。主要なコンポーネントは以下の通り:

- **フロントエンドアプリケーション**: Next.js 15ベースのWebアプリケーション (React 19)
- **ドキュメントサイト**: Next.js + fumadocs-mdxによるドキュメンテーションサイト
- **CLIツール**: npm公開パッケージとしてのコマンドラインツール
- **バックエンドサービス**: Supabase (PostgreSQL, Auth, Realtime, Storage)
- **AIエージェント**: LangGraph.js + OpenAI/LangSmithによるAIエージェントシステム

### サーバー構成

| サーバー種別 | 役割 | スペック | 台数 |
| --- | --- | --- | --- |
| Webサーバー (Vercel Edge) | Next.jsアプリケーションのサーバーレス実行 | Vercel Serverless Functions (自動スケーリング) | 自動スケール |
| APサーバー (Vercel Functions) | Server Actions、API Routes実行 | Vercel Serverless Functions | 自動スケール |
| DBサーバー (Supabase) | PostgreSQL 15、認証、リアルタイム、ストレージ | Supabase マネージドサービス | 1 (マネージド) |

### ネットワーク構成

#### 本番環境ドメイン
- **メインアプリケーション**: `app.liambx.com`
- **ドキュメントサイト**: `liam-docs-sigma.vercel.app`
- **Storybookサイト**: Vercelホスティング

#### CDN / エッジネットワーク
- Vercel Edge Networkによるグローバルなコンテンツ配信
- HTTPS (TLS) による通信暗号化
- 静的アセットのキャッシュ: `s-maxage=60, stale-while-revalidate=86400`

#### 認証フロー
- Supabase Auth + GitHub OAuth連携
- ローカル開発時: `http://localhost:3001`
- 本番環境: `liambx.com`, `app.liambx.com`

## ミドルウェア

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Next.js | 15.4.8 | Webアプリケーションフレームワーク |
| React | 19.1.1 | UIライブラリ |
| Supabase JS Client | 2.75.0 | Supabaseサービス連携 |
| LangChain/LangGraph | 0.4.9 | AIエージェントオーケストレーション |
| Sentry | 9.x / 10.x | エラー監視・パフォーマンスモニタリング |
| PostgreSQL | 15 | データベース (Supabase経由) |
| Turborepo | 2.5.8 | モノレポビルドシステム |
| pnpm | 10.18.3 | パッケージマネージャー |

## 外部サービス連携

| サービス名 | 用途 | 接続方式 |
| --- | --- | --- |
| Vercel | アプリケーションホスティング・CI/CD | Git連携 (自動デプロイ) |
| Supabase | BaaS (PostgreSQL, Auth, Realtime, Storage) | REST API / WebSocket |
| GitHub | OAuth認証、GitHub App連携、リポジトリ管理 | OAuth 2.0 / REST API |
| OpenAI | LLMによるAIエージェント処理 | REST API |
| LangSmith | LLMトレーシング・モニタリング | REST API |
| Sentry | エラートラッキング・パフォーマンス監視 | SDK統合 |
| Resend | メール送信サービス | REST API |
| Slack | 通知連携 (CI/CD障害通知等) | Incoming Webhook |

## スケーリング設計

### 水平スケーリング (Vercel)

- **Serverless Functions**: 自動スケーリング (リクエストベース)
- **Edge Functions**: グローバルエッジネットワークでの分散実行
- **静的アセット**: Vercel CDNによるグローバル配信

### データベーススケーリング (Supabase)

- **Connection Pooling**: PgBouncer (transaction モード)
  - `default_pool_size`: 20
  - `max_client_conn`: 100
- **Realtime**: リアルタイム更新用WebSocket接続
- **ローカル開発ポート設定**:
  - API: 54321
  - Database: 54322
  - Studio: 54323

### ビルドシステム最適化

- **Turborepo**: 並列ビルド (concurrency: 15)
- **キャッシング**: ビルド成果物のキャッシュ管理

## 可用性設計

### Vercelプラットフォーム

- **グローバルエッジネットワーク**: 世界各地のエッジロケーションからの配信
- **自動フェイルオーバー**: リージョン障害時の自動切り替え
- **ゼロダウンタイムデプロイ**: ブルーグリーンデプロイメント

### Supabaseマネージドサービス

- **マネージドPostgreSQL**: 自動バックアップ・リカバリ
- **認証サービス**: 高可用性認証基盤
- **リアルタイム**: WebSocket接続の自動再接続

### 監視・アラート

- **Sentry**: リアルタイムエラー検知
- **Vercel Cron Monitors**: 自動計測 (Sentryインテグレーション)
- **GitHub Actions**: CI/CDパイプラインの監視

## バックアップ設計

| 対象 | 方式 | 頻度 | 保持期間 |
| --- | --- | --- | --- |
| PostgreSQLデータベース | Supabaseマネージドバックアップ | 日次 (自動) | サービスプランに依存 |
| ソースコード | Git (GitHub) | 継続的 | 無期限 |
| 環境変数・シークレット | Vercel Environment Variables | 変更時 | バージョン管理 |
| DBマイグレーション | ファイルベース (Git管理) | 継続的 | Git履歴 |

### マイグレーション管理

- **Supabase Branching**: PRごとのプレビューブランチ自動作成
- **マイグレーションファイル**: `frontend/internal-packages/db/supabase/migrations/`
- **スキーマドリフト検知**: 日次CIチェック (9:00 JST)

## 監視設計

### アプリケーション監視

- **Sentry**: エラートラッキング、パフォーマンスモニタリング
  - ソースマップアップロード
  - React Component Annotation
  - Vercel Cron Monitors連携

### インフラ監視

- **Vercel Dashboard**: デプロイメント、ファンクション実行状況
- **Supabase Dashboard**: データベース、認証、ストレージ監視

### CI/CD監視

- **GitHub Actions**: ワークフロー実行状況
  - `frontend-ci.yml`: フロントエンドCI
  - `database-ci.yml`: データベースCI (PGTap テスト)
  - `e2e_tests.yml`: E2Eテスト (Playwright)
  - `check-schema-drift.yml`: スキーマドリフト検知

### 通知

- **Slack連携**: CI失敗、Supabase障害、E2Eテスト失敗時の通知
- **GitHub Status Checks**: PRへのステータス反映

## 環境構成

### 環境変数管理

| 変数名 | 用途 |
| --- | --- |
| `NEXT_PUBLIC_SUPABASE_URL` | Supabase APIエンドポイント |
| `NEXT_PUBLIC_SUPABASE_ANON_KEY` | Supabase匿名キー |
| `SUPABASE_SERVICE_ROLE_KEY` | Supabaseサービスロールキー |
| `GITHUB_APP_ID` / `GITHUB_CLIENT_ID` | GitHub連携 |
| `OPENAI_API_KEY` | OpenAI API認証 |
| `LANGSMITH_API_KEY` | LangSmithトレーシング |
| `SENTRY_DSN` / `SENTRY_AUTH_TOKEN` | Sentry連携 |
| `RESEND_API_KEY` | メール送信 |
| `POSTGRES_URL` / `POSTGRES_URL_NON_POOLING` | PostgreSQL接続 |
| `LIAM_GITHUB_OAUTH_KEYRING` | GitHub OAuthトークン暗号化キーリング |

### デプロイメント環境

| 環境 | ホスト | 用途 |
| --- | --- | --- |
| Production | Vercel (app.liambx.com) | 本番環境 |
| Preview | Vercel (PRごとのプレビューURL) | PRレビュー |
| Local | localhost:3001 | ローカル開発 |

## 備考

### セキュリティ考慮事項

- **認証**: Supabase Auth + GitHub OAuth
- **暗号化**: AES-256-GCM (GitHub OAuthトークン暗号化)
- **RLS (Row Level Security)**: Supabase PostgreSQLテーブルに適用
- **シークレット管理**: Vercel Environment Variables / `.env.local`

### 技術スタック詳細

- **フロントエンド**: React 19, Next.js 15, TypeScript, CSS Modules
- **ビルド**: Turborepo, pnpm workspaces, Vite (CLIパッケージ)
- **テスト**: Vitest, Playwright (E2E), PGTap (データベース)
- **リンター/フォーマッター**: Biome, ESLint, Stylelint
- **可視化**: @xyflow/react (React Flow)
- **バリデーション**: Valibot

### 開発者向け情報

- **ローカル開発**: `pnpm dev` でローカルサーバー起動 (port 3001)
- **Supabaseローカル**: `pnpm --filter @liam-hq/db supabase:start`
- **テスト実行**: `pnpm test`
- **E2Eテスト**: Vercelデプロイメント完了後に自動実行
