Merge pull request #194 from jphacks/ouita

dd

Author: Daccho

docs/architecture.md

@@ -0,0 +1,130 @@
+# アーキテクチャ図をスライドに貼る方法
+
+このディレクトリには恋AIプロジェクトのMermaid図が含まれています。以下の方法でスライドに貼り付けることができます。
+
+## ファイル一覧
+
+- `overall-architecture.mmd`: 全体アーキテクチャ図
+- `conversation-flow.mmd`: 会話フローシーケンス図
+- `tech-stack.mmd`: 技術スタック図
+
+## 方法1: Mermaid Live Editor (推奨)
+
+最も簡単で高品質な方法です。
+
+1. **Mermaid Live Editorを開く**: https://mermaid.live/
+2. 該当する`.mmd`ファイルの内容をコピー
+3. エディタに貼り付け
+4. 右上の「Actions」→「Export」から形式を選択:
+   - **SVG**: ベクター形式、拡大しても劣化しない(最推奨)
+   - **PNG**: 高品質ラスター画像、背景透過可能
+   - **PDF**: スライドソフトによっては直接貼り付け可能
+5. ダウンロードしてスライドに挿入
+
+### 推奨設定
+- **PowerPoint/Keynote**: SVGまたはPNG(高解像度)
+- **Google Slides**: PNGまたはSVG
+- **LaTeX Beamer**: PDF
+
+## 方法2: VS Code拡張機能
+
+リアルタイムプレビューしながら作業できます。
+
+### 必要な拡張機能
+- **Markdown Preview Mermaid Support** (bierner.markdown-mermaid)
+- **Mermaid Editor** (tomoyukim.vscode-mermaid-editor)
+
+### 手順
+1. VS Codeで該当の`.mmd`ファイルを開く
+2. コマンドパレット(Ctrl/Cmd+Shift+P)→「Mermaid Editor: Preview」
+3. プレビュー画面で右クリック→「Copy Image」または「Export to PNG/SVG」
+4. スライドに貼り付け
+
+## 方法3: Markdown経由でプレビュー
+
+1. [architecture.md](../architecture.md)をVS Codeで開く
+2. プレビューモード(Ctrl/Cmd+Shift+V)で表示
+3. 図を右クリック→「画像をコピー」
+4. スライドに貼り付け
+
+※この方法は解像度が低い場合があるため、重要なプレゼンには方法1を推奨
+
+## 方法4: オンラインツール
+
+### Mermaid Chart (https://www.mermaidchart.com/)
+- アカウント登録が必要
+- 高度な編集機能とチーム共有機能あり
+- PNG/SVG/PDFエクスポート可能
+
+### Kroki (https://kroki.io/)
+- アカウント不要
+- URLにMermaidコードを埋め込んで画像生成
+- 例: `https://kroki.io/mermaid/svg/[base64エンコードされたコード]`
+
+## 方法5: スライドソフト内蔵のMermaidサポート
+
+一部のスライドツールはMermaidを直接サポートしています。
+
+### Slidev (Markdown製スライド)
+```markdown
+```mermaid
+graph TB
+...
+```
+```
+
+### Reveal.js
+```html
+<section>
+  <pre class="mermaid">
+    graph TB
+    ...
+  </pre>
+</section>
+```
+
+### Marp (Markdown製スライド)
+```markdown
+---
+marp: true
+---
+
+# スライドタイトル
+
+```mermaid
+graph TB
+...
+```
+```
+
+## トラブルシューティング
+
+### 日本語が文字化けする
+- Mermaid Live Editorを使用(フォント対応済み)
+- エクスポート時にフォント埋め込みオプションを有効化
+
+### 図が大きすぎる/小さすぎる
+- Mermaid Live Editorで「Configuration」→「Scale」を調整
+- SVGの場合、スライド側で自由にリサイズ可能
+
+### 色を変更したい
+- `.mmd`ファイルの`classDef`部分を編集
+- または、Mermaid Live Editorの「Configuration」→「Theme」で変更
+
+## 推奨ワークフロー
+
+プレゼン用途別の推奨方法:
+
+| 用途 | 推奨方法 | フォーマット |
+|------|---------|------------|
+| 社内プレゼン | Mermaid Live Editor | PNG (透過背景) |
+| 学会発表 | Mermaid Live Editor | SVG または PDF |
+| ポスター | Mermaid Live Editor | SVG (高解像度) |
+| ドキュメント | Markdown内埋め込み | Mermaid コード |
+| Webサイト | Mermaid.js直接レンダリング | Mermaid コード |
+
+## 参考リンク
+
+- Mermaid公式ドキュメント: https://mermaid.js.org/
+- Mermaid Live Editor: https://mermaid.live/
+- Mermaid構文チートシート: https://jojozhuang.github.io/tutorial/mermaid-cheat-sheet/

docs/diagrams/README.md

@@ -0,0 +1,50 @@
+sequenceDiagram
+    participant User as ユーザー
+    participant Frontend as フロントエンド<br/>(Next.js)
+    participant Backend as バックエンド<br/>(Hono/Workers)
+    participant ElevenLabs as ElevenLabs API
+    participant Gemini as Gemini 2.5 Flash
+    participant DB as PostgreSQL
+    participant Storage as Supabase Storage
+
+    User->>Frontend: 音声入力
+    Frontend->>Frontend: AudioRecorder録音
+    Frontend->>Backend: POST /api/stt
+    Backend->>ElevenLabs: 音声→テキスト変換
+    ElevenLabs-->>Backend: テキスト
+    Backend-->>Frontend: 認識テキスト
+
+    Frontend->>Backend: POST /api/conversation/generate
+    Note over Backend: 親密度システム判定<br/>(shy/friendly/open)
+    Backend->>Gemini: AI応答生成リクエスト<br/>(persona, シチュエーション含む)
+    Gemini-->>Backend: AI応答テキスト
+    Backend-->>Frontend: AI応答
+
+    Frontend->>Backend: POST /api/tts
+    Backend->>ElevenLabs: テキスト→音声変換
+    ElevenLabs-->>Backend: 音声ファイル
+    Backend->>Storage: 音声ファイル保存
+    Storage-->>Backend: 保存完了
+    Backend-->>Frontend: 音声URL
+
+    Frontend->>Frontend: Web Audio API<br/>周波数分析(FFT)
+    Frontend->>Frontend: VRMアバター<br/>リップシンク制御
+
+    par 表情分析
+        Frontend->>Frontend: MediaPipe<br/>478点ランドマーク検出
+        Frontend->>Frontend: 笑顔・視線分析
+    end
+
+    Frontend->>Backend: POST /api/sessions/:id/messages
+    Backend->>DB: メッセージ保存
+
+    Frontend->>Backend: POST /api/sessions/:id/gestures
+    Backend->>DB: GestureMetrics保存
+
+    User->>Frontend: セッション終了
+    Frontend->>Backend: POST /api/conversation/feedback
+    Backend->>Gemini: フィードバック生成<br/>(会話履歴+ジェスチャーメトリクス)
+    Gemini-->>Backend: 評価・改善点
+    Backend->>DB: Feedback保存
+    Backend-->>Frontend: フィードバック
+    Frontend->>User: フィードバック表示

docs/diagrams/conversation-flow.mmd

@@ -0,0 +1,140 @@
+graph TB
+    subgraph "クライアント層"
+        User[ユーザー]
+        Partner[パートナー]
+        Camera[カメラ]
+        Mic[マイク]
+    end
+
+    subgraph "フロントエンド - Next.js 15 on Vercel"
+        subgraph "主要ページ"
+            SimPage[/simulation<br/>AI会話シミュレーション]
+            FeedbackPage[/feedback<br/>フィードバック表示]
+            PracticePage[/practice<br/>練習予約]
+            PartnerPage[/partner<br/>パートナーダッシュボード]
+            SessionPage[/session<br/>セッション詳細]
+            TestCallPage[/test-call<br/>通話テスト]
+        end
+
+        subgraph "コアフック"
+            UseConversation[useConversation<br/>会話管理]
+            UseFacialAnalysis[useFacialAnalysis<br/>MediaPipe表情分析]
+            UseLipSync[useLipSync<br/>Web Audio APIリップシンク]
+            UseVRM[useVRM<br/>VRM制御]
+            UseAgoraCall[useAgoraCall<br/>Agoraビデオ通話]
+        end
+
+        subgraph "3D/UI層"
+            VRMAvatar[VRMアバター<br/>React Three Fiber]
+            MediaPipe[MediaPipe<br/>478点顔ランドマーク]
+            AudioRecorder[AudioRecorder<br/>音声録音]
+        end
+    end
+
+    subgraph "バックエンド - Hono on Cloudflare Workers"
+        subgraph "APIルート"
+            SessionsAPI[/api/sessions<br/>セッション管理]
+            ConversationAPI[/api/conversation<br/>AI会話生成]
+            FeedbackAPI[/api/feedback<br/>フィードバック生成]
+            SpeechAPI[/api/stt, /api/tts<br/>音声処理]
+            AgoraAPI[/api/agora/token<br/>トークン生成]
+            PartnersAPI[/api/partners<br/>パートナー管理]
+            AuthAPI[/api/auth<br/>Better Auth]
+        end
+
+        subgraph "サービス層"
+            ConversationService[conversation.ts<br/>ビジネスロジック]
+            AIClient[ai-client.ts<br/>Gemini APIクライアント]
+            STTService[stt.ts<br/>STT/TTS処理]
+        end
+    end
+
+    subgraph "データベース層 - Supabase"
+        PostgreSQL[(PostgreSQL)]
+        Storage[(Supabase Storage<br/>音声ファイル)]
+    end
+
+    subgraph "外部サービス"
+        Gemini[Google Gemini 2.5 Flash<br/>AI会話・フィードバック]
+        ElevenLabs[ElevenLabs API<br/>TTS/STT]
+        Agora[Agora RTC<br/>ビデオ通話]
+    end
+
+    subgraph "データモデル - Prisma"
+        Conversation[Conversation<br/>会話セッション]
+        Message[Message<br/>メッセージ履歴]
+        Feedback[Feedback<br/>フィードバック]
+        GestureMetrics[GestureMetrics<br/>表情・視線データ]
+        HumanPartnerSession[HumanPartnerSession<br/>人間パートナーセッション]
+        HumanPartnerFeedback[HumanPartnerFeedback<br/>パートナーフィードバック]
+        PracticeSlot[PracticeSlot<br/>予約枠]
+        UserModel[User<br/>ユーザー]
+    end
+
+    %% クライアント → フロントエンド
+    User --> SimPage
+    User --> FeedbackPage
+    User --> PracticePage
+    Partner --> PartnerPage
+    Camera --> MediaPipe
+    Mic --> AudioRecorder
+
+    %% フロントエンド内部フロー
+    SimPage --> UseConversation
+    SimPage --> UseFacialAnalysis
+    SimPage --> UseVRM
+    UseConversation --> AudioRecorder
+    UseFacialAnalysis --> MediaPipe
+    UseVRM --> VRMAvatar
+    UseLipSync --> VRMAvatar
+
+    TestCallPage --> UseAgoraCall
+    SessionPage --> UseAgoraCall
+
+    %% フロントエンド → バックエンド
+    UseConversation --> SpeechAPI
+    UseConversation --> ConversationAPI
+    FeedbackPage --> FeedbackAPI
+    PracticePage --> PartnersAPI
+    PartnerPage --> PartnersAPI
+    UseAgoraCall --> AgoraAPI
+    SimPage --> SessionsAPI
+
+    %% バックエンド内部フロー
+    ConversationAPI --> ConversationService
+    FeedbackAPI --> ConversationService
+    ConversationService --> AIClient
+    SpeechAPI --> STTService
+
+    %% バックエンド → 外部サービス
+    AIClient --> Gemini
+    STTService --> ElevenLabs
+    AgoraAPI --> Agora
+
+    %% バックエンド → データベース
+    SessionsAPI --> PostgreSQL
+    ConversationService --> PostgreSQL
+    STTService --> Storage
+    PartnersAPI --> PostgreSQL
+    AuthAPI --> PostgreSQL
+
+    %% データモデルリレーション
+    Conversation --> Message
+    Conversation --> Feedback
+    Conversation --> GestureMetrics
+    HumanPartnerSession --> HumanPartnerFeedback
+    HumanPartnerSession --> PracticeSlot
+    UserModel --> HumanPartnerSession
+
+    %% スタイリング
+    classDef frontend fill:#61dafb,stroke:#333,stroke-width:2px,color:#000
+    classDef backend fill:#f39c12,stroke:#333,stroke-width:2px,color:#000
+    classDef database fill:#2ecc71,stroke:#333,stroke-width:2px,color:#000
+    classDef external fill:#e74c3c,stroke:#333,stroke-width:2px,color:#fff
+    classDef model fill:#9b59b6,stroke:#333,stroke-width:2px,color:#fff
+
+    class SimPage,FeedbackPage,PracticePage,PartnerPage,SessionPage,TestCallPage,UseConversation,UseFacialAnalysis,UseLipSync,UseVRM,UseAgoraCall,VRMAvatar,MediaPipe,AudioRecorder frontend
+    class SessionsAPI,ConversationAPI,FeedbackAPI,SpeechAPI,AgoraAPI,PartnersAPI,AuthAPI,ConversationService,AIClient,STTService backend
+    class PostgreSQL,Storage database
+    class Gemini,ElevenLabs,Agora external
+    class Conversation,Message,Feedback,GestureMetrics,HumanPartnerSession,HumanPartnerFeedback,PracticeSlot,UserModel model

docs/diagrams/overall-architecture.mmd

@@ -0,0 +1,47 @@
+graph LR
+    subgraph "フロントエンド技術"
+        NextJS[Next.js 15<br/>React 19]
+        R3F[React Three Fiber<br/>Three.js]
+        VRM[@pixiv/three-vrm<br/>VRMモデル]
+        MediaPipeLib[MediaPipe<br/>顔分析]
+        WebAPIs[Web APIs<br/>Speech/Audio]
+        Agora1[Agora RTC SDK]
+    end
+
+    subgraph "バックエンド技術"
+        Hono[Hono Framework]
+        Workers[Cloudflare Workers]
+        ZodOpenAPI[@hono/zod-openapi]
+        BetterAuth[Better Auth]
+    end
+
+    subgraph "データ層"
+        Prisma[Prisma ORM]
+        PrismaAccelerate[Prisma Accelerate]
+        Supabase[Supabase<br/>PostgreSQL + Storage]
+    end
+
+    subgraph "AI/外部サービス"
+        Gemini2[Google Gemini<br/>2.5 Flash]
+        ElevenLabs2[ElevenLabs<br/>TTS/STT]
+        Agora2[Agora RTC]
+    end
+
+    NextJS --> R3F
+    R3F --> VRM
+    NextJS --> MediaPipeLib
+    NextJS --> WebAPIs
+    NextJS --> Agora1
+
+    Hono --> Workers
+    Hono --> ZodOpenAPI
+    Hono --> BetterAuth
+
+    Hono --> Prisma
+    Prisma --> PrismaAccelerate
+    PrismaAccelerate --> Supabase
+    NextJS --> Prisma
+
+    Hono --> Gemini2
+    Hono --> ElevenLabs2
+    Hono --> Agora2