# アーキテクチャ設計書

## 概要

本ドキュメントはGiselle（AIワークフローエンジン）のアプリケーションアーキテクチャを定義するものである。Giselleはビジュアルエディタを通じてAIワークフローを設計・実行するためのプラットフォームであり、Turborepoを用いたモノレポ構成でSDKパッケージとアプリケーションを管理している。

## システム全体構成

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

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

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

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| Vercel AI SDK | SDK統合 | LLMプロバイダー（OpenAI, Anthropic, Google等）との通信 |
| Supabase | Auth API / SDK | ユーザー認証・認可 |
| PostgreSQL (Vercel Postgres) | Drizzle ORM | データ永続化・ベクトルストア |
| GitHub | REST API / Webhooks | リポジトリ連携・トリガー |
| Stripe | API v2 | 課金・サブスクリプション管理 |
| Vercel Blob Storage | SDK | ファイルストレージ |
| Langfuse | SDK | LLMオブザーバビリティ |

## レイヤー構成

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

**SDK駆動のレイヤードアーキテクチャ**

GiselleはSDKパッケージを中心としたレイヤード構成を採用している。コアとなる`@giselles-ai/*`パッケージ群がドメインロジックを担い、アプリケーション層（Next.js App Router）がUIとAPIルーティングを提供する。

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Presentation | ビジュアルワークフローエディタ、ユーザーインタラクション | `@giselle-internal/workflow-designer-ui`, React Flow |
| Application | ルーティング、認証、セッション管理 | Next.js App Router, Supabase Auth, middleware |
| SDK/Engine | ワークフロー実行、タスク管理、Generation処理 | `@giselles-ai/giselle`, `@giselles-ai/react` |
| Protocol | ドメイン型定義、Zodスキーマ | `@giselles-ai/protocol` |
| Infrastructure | データアクセス、外部サービス統合 | `drizzle-orm`, `@giselles-ai/storage`, `@giselles-ai/rag` |

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

- **依存の方向**: Presentation → Application → SDK/Engine → Protocol ← Infrastructure
- **許可される参照**: 上位レイヤーから下位レイヤーへの参照、ProtocolはInfrastructureからも参照可能
- **禁止される参照**: 下位レイヤーから上位レイヤーへの直接参照、SDK間の循環参照

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| Workspace | AIワークフローの設計・保存 | `@giselles-ai/protocol/workspace`, `@giselles-ai/giselle/workspaces` |
| Task | ワークフロー実行インスタンス管理 | `@giselles-ai/protocol/task`, `@giselles-ai/giselle/tasks` |
| Generation | 単一ステップ実行・LLM呼び出し | `@giselles-ai/protocol/generation`, `@giselles-ai/giselle/generations` |
| Node | ワークフローノード（Operation/Variable） | `@giselles-ai/protocol/node`, `@giselles-ai/node-registry` |
| Trigger | イベント駆動実行 | `@giselles-ai/protocol/trigger`, `@giselles-ai/trigger-registry` |
| Integration | 外部サービス連携 | `@giselles-ai/github-tool`, `@giselles-ai/web-search` |
| RAG | ベクトル検索・Embedding | `@giselles-ai/rag` |

### パッケージ構造

```
/
├── apps/
│   ├── studio.giselles.ai/      # Giselle Cloud (Next.js 16, App Router)
│   │   ├── app/                  # ルーティング・ページ
│   │   │   ├── (auth)/          # 認証関連ルート
│   │   │   ├── (main)/          # メインアプリルート
│   │   │   ├── api/             # API Routes
│   │   │   └── webhooks/        # Webhook エンドポイント
│   │   ├── db/                  # Drizzle スキーマ・DB接続
│   │   └── lib/                 # アプリ固有ユーティリティ
│   └── ui.giselles.ai/          # UIコンポーネントショーケース
├── packages/                     # SDK パッケージ (@giselles-ai/*)
│   ├── protocol/                # コアドメイン型・Zodスキーマ
│   ├── giselle/                 # エンジン実装（タスク・Generation）
│   ├── react/                   # React hooks・コンポーネント
│   ├── nextjs/                  # Next.js統合
│   ├── http/                    # HTTPルーター
│   ├── language-model/          # LLM抽象化
│   ├── language-model-registry/ # プロバイダー実装
│   ├── rag/                     # RAGパイプライン
│   ├── storage/                 # ストレージ抽象化
│   ├── vault/                   # シークレット管理
│   ├── logger/                  # ロギング（Pino）
│   ├── github-tool/             # GitHub連携
│   └── ...
└── internal-packages/           # 内部共有パッケージ (@giselle-internal/*)
    ├── ui/                      # 共通UIコンポーネント（Radix UI）
    └── workflow-designer-ui/    # ビジュアルワークフローエディタ（React Flow）
```

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

**コア依存フロー:**

```
workflow-designer-ui
    ↓
@giselles-ai/react → @giselles-ai/giselle
    ↓
@giselles-ai/protocol
    ↓
@giselles-ai/language-model-registry → @giselles-ai/language-model
```

## ミドルウェア構成

### データベース

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| RDB | PostgreSQL (Vercel Postgres) | - | ユーザー、チーム、ワークスペース、タスク管理 |
| Vector Store | pgvector | 0.2.1 | Embedding格納・ベクトル検索 |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| Vercel Edge Config | 1.4.0 | Feature Flags | 動的 |
| SWR (クライアント) | 2.3.6 | データフェッチキャッシュ | 設定依存 |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Vercel Functions | 2.2.11 | 非同期Generation処理 |

### 検索エンジン

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| pgvector (HNSW Index) | 0.2.1 | 類似度検索（RAG） |

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

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Vercel AI SDK | 5.0.101 | LLMプロバイダー統合 |
| Drizzle ORM | 0.44.2 | TypeScript ORM |
| Zod v4 | 4.1.12 | スキーマバリデーション |
| Zustand | 5.0.8 | クライアント状態管理 |

## データフロー

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

1. **クライアント**: React（workflow-designer-ui）からAPI呼び出し
2. **Next.js Route Handler**: `/api/giselle/[...path]` でリクエスト受信
3. **HTTP Router** (`@giselles-ai/http`): パス解析・ハンドラーディスパッチ
4. **Giselle Engine** (`@giselles-ai/giselle`): ビジネスロジック実行
5. **Protocol**: Zodスキーマによる入出力バリデーション
6. **Infrastructure**: データベース・外部サービスアクセス
7. **レスポンス**: JSON形式でクライアントへ返却

### 非同期処理の流れ

1. **タスク作成**: `createTask` でTask/Generationレコード生成
2. **タスク開始**: `startTask` でシーケンス実行キュー投入
3. **Generation実行**: `runTask` でシーケンスを順次処理
4. **ステップ実行**: `executeStep` でGeneration種別に応じた処理分岐
   - `textGeneration`: LLM呼び出し (`startContentGeneration`)
   - `imageGeneration`: 画像生成 (`generateImage`)
   - `action`: アクション実行 (`executeAction`)
   - `trigger`: トリガー解決 (`resolveTrigger`)
   - `query`: クエリ実行 (`executeQuery`)
5. **完了通知**: コールバック経由で状態更新

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

1. **Workspace**: JSON形式でDBに保存（nodes, connections含む）
2. **Task**: 実行ごとにレコード作成、状態更新はパッチ適用
3. **Generation**: ステータス遷移（created→queued→running→completed/failed）
4. **Embedding**: pgvectorに格納、HNSWインデックスで高速検索

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| Supabase Auth | `lib/supabase/middleware.ts`, `@supabase/ssr` | ユーザー認証 |
| チームメンバーシップ | `db/schema.ts` (team_memberships) | リソースアクセス制御 |
| APIキー認証 | `db/schema.ts` (api_keys), scryptハッシュ | API認証 |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | Pino (`@giselles-ai/logger`) | stdout (Vercel Logs) |
| LLMトレース | Langfuse SDK | Langfuse |
| エラーモニタリング | Sentry (`@sentry/nextjs`) | Sentry |

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

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| バリデーションエラー | ZodError catch | 400 Bad Request |
| 認証エラー | Supabase middleware | 401 Unauthorized / リダイレクト |
| リソース不在 | 明示的nullチェック | 404 Not Found |
| 使用量制限 | UsageLimitError | 429 Too Many Requests |
| 内部エラー | グローバルエラーハンドラー | 500 Internal Server Error |

**カスタムエラークラスの設計:**

- Symbolマーカーによるクロスパッケージエラー識別
- `isInstance` 静的メソッドによる型ガード

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

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| 単一テーブル操作 | Drizzle ORM自動管理 | Read Committed (デフォルト) |
| 複数テーブル操作 | パッチキュー (`createPatchQueue`) | 最終整合性 |

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

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

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 単一責任の原則 | パッケージ分割 | protocol（型定義）、giselle（エンジン）、react（UI連携） |
| 依存性逆転の原則 | Storage抽象化 | `@giselles-ai/storage` インターフェース |
| Discriminated Union | Node型 | `z.discriminatedUnion("type", [OperationNode, VariableNode])` |
| Branded Types | ID型 | `createIdGenerator("nd")` → `nd_xxx` |
| Fail Fast | 入力検証 | Zodスキーマによる早期バリデーション |
| Exhaustive Check | Switch文 | `never` 型による網羅性チェック |

### コーディング規約

- **ファイル名**: kebab-case (`user-profile.ts`)
- **コンポーネント名**: PascalCase (`UserProfile`)
- **変数・関数名**: camelCase (`calculateTotalPrice`)
- **Boolean変数**: is/has/can/should プレフィックス
- **フォーマッター**: Biome（タブインデント、ダブルクォート）
- **TypeScript**: 明示的型注釈、Zodによるランタイムバリデーション
- **React**: 関数コンポーネント + Hooks、Zustand選択的サブスクリプション
- **非同期**: async/await優先、try/catchによるエラーハンドリング

## 備考

### Feature Flags

- 本番未リリース機能はFeature Flagで保護
- `apps/studio.giselles.ai/flags.ts` で定義
- 開発環境: 環境変数、本番: Vercel Edge Config

### モノレポビルド

- Turborepo によるタスク依存管理
- `pnpm build-sdk`: SDKパッケージのビルド（アプリビルド前に必須）
- パッケージ間依存は `workspace:*` で参照
