# アーキテクチャ設計書

## 概要

本ドキュメントは、Liam (liam-frontend) プロジェクトのアプリケーションアーキテクチャを定義する。Liamは、データベーススキーマからER図を生成・可視化し、AIエージェントによるスキーマ設計支援を提供するWebアプリケーションである。モノレポ構成を採用し、複数のパッケージを効率的に管理している。

## システム全体構成

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

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

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

| 外部システム | 連携方式 | 用途 |
| --- | --- | --- |
| Supabase (PostgreSQL) | REST API / Realtime | データ永続化、認証、リアルタイム通信 |
| GitHub API | REST API / OAuth | リポジトリ連携、スキーマファイル取得、認証 |
| OpenAI API | REST API (LangChain経由) | AIエージェントによるスキーマ分析・設計支援 |
| Sentry | SDK統合 | エラー監視、パフォーマンスモニタリング |
| Vercel | ホスティング | デプロイ、CDN、エッジ関数 |
| Figma API | REST API | デザイントークン取得、CSS変数生成 |

## レイヤー構成

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

**モノレポ + モジュラーアーキテクチャ**

- Turborepo によるモノレポ管理
- pnpm workspaces によるパッケージ管理
- 機能別パッケージ分割による関心の分離
- Next.js App Router による Server Components / Client Components の分離

### レイヤー定義

| レイヤー | 責務 | 主なコンポーネント |
| --- | --- | --- |
| Presentation | UI表示、ユーザーインタラクション | `@liam-hq/app`, `@liam-hq/docs`, `@liam-hq/ui`, `@liam-hq/erd-core` |
| Application | ビジネスロジック、ワークフロー制御 | `@liam-hq/agent`, Server Actions, API Routes |
| Domain | ドメインモデル、スキーマ定義 | `@liam-hq/schema`, Valibot スキーマ |
| Infrastructure | 外部サービス連携、データアクセス | `@liam-hq/db`, `@liam-hq/github`, Supabase Client |

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

- **依存の方向性**: Presentation -> Application -> Domain <- Infrastructure
- **許可される参照**: 上位レイヤーから下位レイヤーへの参照
- **禁止される参照**: 下位レイヤーから上位レイヤーへの直接参照
- **例外**: Infrastructure層はDomain層のインターフェースを実装

## モジュール構成

### ドメイン分割

| ドメイン | 責務 | 関連モジュール |
| --- | --- | --- |
| ERD可視化 | スキーマの視覚的表現、インタラクティブ操作 | `@liam-hq/erd-core`, `@xyflow/react` |
| スキーマ解析 | 各種DBスキーマフォーマットの解析 | `@liam-hq/schema`, `@prisma/internals` |
| AIエージェント | スキーマ設計の自動化・支援 | `@liam-hq/agent`, LangGraph, LangChain |
| 認証・認可 | ユーザー認証、組織管理 | `@liam-hq/db`, Supabase Auth |
| プロジェクト管理 | プロジェクト、セッション、リポジトリ連携 | `@liam-hq/app`, `@liam-hq/github` |

### パッケージ構造

```
liam-frontend/
├── frontend/
│   ├── apps/
│   │   ├── app/                    # @liam-hq/app - メインWebアプリケーション (Next.js 15)
│   │   │   ├── app/                # App Router ページ・レイアウト
│   │   │   ├── features/           # 機能別コンポーネント群
│   │   │   └── libs/               # ユーティリティ、定数
│   │   └── docs/                   # @liam-hq/docs - ドキュメントサイト (fumadocs)
│   │
│   ├── packages/                   # 公開パッケージ
│   │   ├── cli/                    # @liam-hq/cli - CLIツール
│   │   ├── erd-core/               # @liam-hq/erd-core - ERD可視化コア
│   │   ├── schema/                 # @liam-hq/schema - スキーマパーサー
│   │   └── ui/                     # @liam-hq/ui - 共通UIコンポーネント
│   │
│   └── internal-packages/          # 内部パッケージ
│       ├── agent/                  # @liam-hq/agent - AIエージェントシステム
│       ├── db/                     # @liam-hq/db - データベースユーティリティ
│       ├── github/                 # @liam-hq/github - GitHub連携
│       ├── mcp-server/             # @liam-hq/mcp-server - MCP Server実装
│       ├── pglite-server/          # @liam-hq/pglite-server - PGliteサーバー
│       └── security/               # @liam-hq/security - セキュリティユーティリティ
│
├── docs/                           # プロジェクトドキュメント
├── .github/                        # GitHub Actions, PR テンプレート
└── turbo.json                      # Turborepo設定
```

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

主要パッケージ間の依存関係:

- `@liam-hq/app` -> `@liam-hq/agent`, `@liam-hq/db`, `@liam-hq/erd-core`, `@liam-hq/schema`, `@liam-hq/ui`, `@liam-hq/github`, `@liam-hq/security`
- `@liam-hq/cli` -> `@liam-hq/erd-core`, `@liam-hq/schema`
- `@liam-hq/erd-core` -> `@liam-hq/ui`, `@liam-hq/schema`
- `@liam-hq/agent` -> `@liam-hq/db`, `@liam-hq/schema`, `@liam-hq/pglite-server`
- `@liam-hq/docs` -> `@liam-hq/ui`

## ミドルウェア構成

### データベース

| 種類 | ミドルウェア | バージョン | 用途 |
| --- | --- | --- | --- |
| RDB | PostgreSQL (Supabase) | 15+ | メインデータストア、認証 |
| ブラウザ内DB | PGlite | 0.3.x | クライアントサイドでのSQL実行・テスト |

### キャッシュ

| ミドルウェア | バージョン | 用途 | TTL |
| --- | --- | --- | --- |
| Next.js Data Cache | Next.js 15組み込み | ページ・データキャッシュ | 設定に依存 |
| Vercel Edge Cache | Vercel組み込み | 静的アセット、API応答 | max-age=0, s-maxage=60 |

### メッセージキュー

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| Supabase Realtime | 最新 | リアルタイム通知、スキーマ更新通知 |

### 検索エンジン

該当なし（現時点では専用検索エンジンは使用していない）

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

| ミドルウェア | バージョン | 用途 |
| --- | --- | --- |
| LangGraph | 0.4.x | AIエージェントワークフロー制御 |
| LangChain | 0.3.x | LLM統合、ツール呼び出し |
| Sentry | 9.x / 10.x | エラー監視、パフォーマンストレーシング |

## データフロー

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

1. **ユーザーリクエスト受信**: Next.js Middleware でリクエストを受信
2. **認証チェック**: Supabase Auth を使用してセッション検証
3. **ルーティング**: App Router によるページルーティング
4. **データ取得**: Server Components / Server Actions でSupabaseからデータ取得
5. **レンダリング**: React 19 による Server/Client Components のハイブリッドレンダリング
6. **レスポンス返却**: HTML/JSONをクライアントに返却

### 非同期処理の流れ

**AIエージェント (LangGraph) ワークフロー:**

1. **ユーザー入力受信**: デザインセッションでユーザーがメッセージを送信
2. **リードエージェント**: 入力を分析し、適切なサブエージェントを選択
3. **PMエージェント**: 要件を分析し、構造化された要件を出力
4. **DBエージェント**: スキーマ変更を生成
5. **QAエージェント**: 生成されたスキーマをテスト・検証
6. **結果返却**: リードエージェントが最終結果をユーザーに返却

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

1. **Server Action呼び出し**: クライアントからServer Actionを実行
2. **バリデーション**: Valibot によるスキーマ検証
3. **Supabase操作**: `@liam-hq/db` 経由でCRUD操作実行
4. **RLS適用**: Row Level Security による認可チェック
5. **コミット**: トランザクション完了
6. **Realtime通知**: 必要に応じて購読者に通知

## 横断的関心事

### 認証・認可

| 方式 | 実装箇所 | 対象 |
| --- | --- | --- |
| OAuth 2.0 (GitHub) | Supabase Auth, `app/auth/callback/` | ユーザー認証 |
| Session Cookie | Next.js Middleware, Supabase SSR | セッション管理 |
| Row Level Security | Supabase PostgreSQL | データアクセス制御 |
| Organization-based Access | `@liam-hq/db` RLS Policies | マルチテナント分離 |

### ロギング・監査

| 種類 | 実装方式 | 保存先 |
| --- | --- | --- |
| アプリケーションログ | console.log / Sentry | Sentry / 標準出力 |
| 監査ログ | Supabase RLS Policies | PostgreSQL |
| アクセスログ | Vercel Logs | Vercel Dashboard |

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

| エラー種別 | ハンドリング方式 | レスポンス |
| --- | --- | --- |
| バリデーションエラー | Valibot / neverthrow | 400 Bad Request |
| 認証エラー | Middleware リダイレクト | 302 -> /login |
| 認可エラー | RLS拒否 | 403 Forbidden |
| サーバーエラー | global-error.tsx / Sentry | 500 Internal Server Error |
| ネットワークエラー | neverthrow Result型 | エラーUIコンポーネント |

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

| 範囲 | 管理方式 | 分離レベル |
| --- | --- | --- |
| 単一テーブル操作 | Supabase RPC | READ COMMITTED |
| 複数テーブル操作 | SQL BEGIN/COMMIT | READ COMMITTED |
| AIエージェント状態 | LangGraph Checkpointer | アプリケーションレベル |

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

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

| 原則 | 適用箇所 | 実装例 |
| --- | --- | --- |
| 単一責任の原則 (SRP) | パッケージ分割 | 機能別パッケージ (`schema`, `ui`, `agent`) |
| 依存性逆転の原則 (DIP) | DB層 | `createServerClient` / `createBrowserClient` 抽象化 |
| 関心の分離 | レイヤー構成 | Presentation / Application / Domain / Infrastructure |
| 12-Factor Agents | AIエージェント | プロンプトの明示的管理、LangGraph低レベルAPI使用 |

### コーディング規約

- **TypeScript**: 厳格な型定義、Valibot による実行時バリデーション
- **命名規則**: Event handlers は `handle` プレフィックス（例: `handleClick`）
- **エクスポート**: 名前付きエクスポートのみ使用（default export 禁止）
- **スタイリング**: CSS Modules、`@liam-hq/ui` のCSS変数使用
- **テスト**: 観察可能な振る舞いのテスト、実装詳細は避ける
- **コンポーネント**: Server Components優先、必要時のみClient Components
- **早期リターン**: 可読性向上のため積極的に使用
- **コード削除**: 不要なコードは恐れず削除（Git が記憶）

## 備考

### 技術選定の背景

- **React 19 / Next.js 15**: 最新のServer Components、Server Actionsによるパフォーマンス最適化
- **Turborepo**: 高速なモノレポビルド、キャッシュによる開発効率向上
- **LangGraph**: 複雑なAIワークフローの状態管理、再現可能な実行
- **Supabase**: PostgreSQL + 認証 + Realtime の統合プラットフォーム
- **Valibot**: 軽量なランタイムバリデーション、バンドルサイズ最適化

### 今後の拡張ポイント

- MCPサーバーによる外部ツール連携の拡充
- スキーマパーサーの対応フォーマット追加
- AIエージェントの機能拡張（新規サブエージェント追加）
