Hybrid Architecture & Multi-Platform Strategy

1. 概要

本プロジェクト "BluePeriod" は、Webアプリケーション (Next.js) としての利便性と、デスクトップアプリケーション (Tauri) としての強力な機能（ローカルLLM、CORS回避）を両立させる「ハイブリッドアーキテクチャ」を採用しています。

本ドキュメントでは、将来的なマルチプラットフォーム化（Web, Mobile/Capacitor, Desktop/Tauri）を見据え、「ソースコードはNext.jsの一つのみ」 で管理するための設計指針と実装ルールを定義します。

1.1. 現状の実装具合

• 2026年2月14日時点 現在この方針は鋭意実践予定であり、現状は分離があまりできていません。 新規実装に対する作業においては、この方針を採用して負債を蓄積していかないよう努めます。

2. コア・コンセプト

2.1. Logic Extraction (脳みその分離)

Next.jsのAPI Route (/app/api/...) は、Web版においては必須（APIキー隠蔽やCORS回避のため）ですが、デスクトップ版（Static Export）では利用できません。 したがって、ビジネスロジックやAI処理の実装をAPI Route内に直接記述することは禁止します。

• ルール: ロジックは「どこでも動く純粋な関数」として src/lib/features/... 等に切り出すこと。
• API Routeの役割: 単なる「Web版のためのHTTPインターフェース（Controller）」に徹する。入力を受け取り、src/lib の関数を呼び出し、結果を返すだけにする。

2.2. Hono as the Web Adapter (Web用共通基盤)

Web版においては、Hono を統一のエントリポイント（/api/[[...route]]）として採用します。

• 役割: ブラウザからの HTTPリクエストを捌き、認証を検証し、src/lib/features の「脳みそ」を呼び出す。
• メリット:
  • Vercel制限の回避: すべての API を1つの Serverless Function に集約できる。
  • ポータビリティ: Hono は Web標準ベースのため、Cloudflare Workers やブラウザの Service Worker上でも動作可能。
  • AIフレンドリー: 機能ごとにモジュール分割された src/server/api/*.ts 構成により、メンテナンス性が向上する。

2.3. Environment Adapter (環境アダプター)

UIコンポーネントやクライアントサイドのロジックは、実行環境（Web vs Desktop vs Mobile）を意識せず動作する必要があります。

• ルール: UI層はAPIエンドポイントを直接 fetch するのではなく、「Adapter」 と呼ばれる抽象化レイヤーを経由して機能を呼び出す。

• 環境別アーキテクチャ概観:

  • Web (Next.js/Vercel): UI → fetch('/api/...') → Cloud Hono → Logic
  • Desktop (Tauri): UI → 直接呼び出し → Logic (オフライン/ローカルLLM対応)
  • Mobile (Capacitor): UI → 直接呼び出し/一部API → Logic (オフライン対応)

• Adapterの責務: 環境変数（例: __TAURI__）や設定に基づいて、通信経路を自動的に切り替える。

  • Managed Feature (運営負担): どの環境からも、認証付きで「クラウド上の Hono API」を叩く。
  • Self-hosted Feature (ユーザー負担/BYOK): デスクトップ版では API を介さず、ローカルの Ollama や SDK を直接利用する。

3. 実装ガイドライン

3.1. AI機能の実装パターン

新しいAI機能（例: Adit）を追加する際は、以下の構成を遵守してください。

1. Core Logic (src/lib/...):

   • AIモデル (BaseChatModel) を引数として受け取り、処理を行う純粋なクラス/関数。
   • 特定のHTTPリクエスト/レスポンス型に依存しない。
   • 例: Adit クラス。

2. Web Adapter (API Route):

   • src/app/api/... に配置。
   • リクエストボディを解析し、Core Logicを呼び出す。
   • この中で ChatOpenAI 等をインスタンス化し、Core Logicに注入する（DI）。

3. Client Tool / Adapter:

   • src/ai/agents/tools/... に配置。
   • 環境に応じて、Web Adapter (API) を叩くか、(将来的に) Core Logicを直接呼ぶかを分岐できるようにする。
   • 現状の暫定措置: Web版がメインであるため、まずはAPI Routeを叩く実装を行うが、「ロジックが分離されていること」 が担保されていれば、将来の差し替えは容易である。

3.2. ビルド戦略 (Conditional Build)

• Web: 通常通り next build。
• Desktop: next.config.js の設定により API Routes をビルド対象外とし、output: 'export' で完全な静的ファイルとして書き出す。

4. チェックリスト

新機能を実装する際は、以下を自問してください。

• そのロジックは src/app/api の外にありますか？
• そのロジックは NextRequest / NextResponse オブジェクトに依存していませんか？
• API Route は単なる「薄いラッパー」になっていますか？

---

関連ドキュメント:

• 01_architecture
• 12_ai_agent_architecture