ASR-LLM-TTS 音声対話アシスタントフロントエンド

🏗️ アーキテクチャの概要

ASR-LLM-TTS 音声対話アシスタントのフロントエンドは、モダンな Next.js + React 19 アーキテクチャを採用し、TailwindCSS と shadcn/ui コンポーネントライブラリを組み合わせて、レスポンシブで操作しやすいユーザーインターフェースを実現しています。フロントエンドは WebSocket でバックエンドとリアルタイムに通信し、テキスト入力、音声認識結果の表示、LLM 応答のストリーミング表示、システム状態の可視化に対応しています。

主な特長

🌐 モダンなアーキテクチャ：Next.js 15 + React 19 + TypeScript
🎨 洗練された UI デザイン：TailwindCSS + shadcn/ui コンポーネントライブラリ
🔄 リアルタイム通信：WebSocket による双方向通信プロトコル
📱 レスポンシブデザイン：モバイルとデスクトップに完全対応
🎯 3D による状態の可視化：Three.js で実装した動的な状態表示球体
🌍 国際化対応：中国語/英語の 2 言語切り替え
⚡ ストリーミング体験：LLM の応答をリアルタイムにストリーミング表示

技術スタック

コンポーネント	採用技術	バージョン	説明
Web フレームワーク	Next.js	15.2.4	React フルスタックフレームワーク
UI ライブラリ	React	19	最新版の React
言語	TypeScript	5.x	型安全な開発
スタイルフレームワーク	TailwindCSS	3.4.17	ユーティリティファースト CSS フレームワーク
UI コンポーネント	shadcn/ui	latest	Radix UI ベースのコンポーネントライブラリ
3D レンダリング	Three.js	latest	WebGL 3D 可視化ライブラリ
状態管理	React Context API	-	ネイティブの状態管理
通信プロトコル	WebSocket	-	リアルタイム双方向通信

📁 プロジェクト構成

Frontend/
├── app/                          # Next.js应用目录
│   ├── globals.css               # 全局样式
│   ├── layout.tsx                # 应用布局
│   └── page.tsx                  # 主页面
├── components/                   # 组件目录
│   ├── app-state-provider.tsx    # 统一状态管理提供者
│   ├── chat-interface.tsx        # 聊天界面组件
│   ├── sphere.tsx                # 3D状态可视化组件
│   ├── websocket-context.tsx     # WebSocket上下文（兼容层）
│   ├── theme-provider.tsx        # 主题提供者
│   ├── language-switcher.tsx     # 语言切换组件
│   └── ui/                       # UI组件库
│       ├── button.tsx            # 按钮组件
│       ├── input.tsx             # 输入框组件
│       └── ...                   # 其他shadcn/ui组件
├── hooks/                        # 自定义钩子
│   ├── use-mobile.tsx            # 移动设备检测钩子
│   └── use-toast.ts              # 提示消息钩子
├── lib/                          # 工具库
│   ├── app-state-manager.ts      # 应用状态管理器
│   ├── utils.ts                  # 通用工具函数
│   └── i18n/                     # 国际化系统
│       ├── config.ts             # i18n配置
│       ├── context.tsx           # i18n上下文
│       └── locales/              # 语言文件
├── public/                       # 静态资源
├── docs/                         # 详细文档 (新增)
│   ├── frontend-architecture.md  # 前端架构详解
│   ├── websocket-integration.md  # WebSocket通信集成
│   ├── ui-components.md          # UI组件系统
│   ├── state-management.md       # 状态管理详解
│   ├── i18n-system.md           # 国际化系统
│   └── deployment.md            # 部署指南
├── package.json                  # 项目依赖
├── tailwind.config.ts           # TailwindCSS配置
├── next.config.mjs              # Next.js配置
└── tsconfig.json                # TypeScript配置

🚀 クイックスタート

動作環境

Node.js 18.x 以降
npm 9.x 以降
モダンブラウザ（WebSocket と WebGL に対応したもの）

インストールと実行

# 安装依赖
npm install

# 开发环境运行
npm run dev

# 生产环境构建
npm run build
npm run start

# 代码检查
npm run lint

環境変数の設定

.env.local ファイルを作成します：

# WebSocket连接地址
NEXT_PUBLIC_WEBSOCKET_URL=ws://localhost:8000/ws/chat

🔗 バックエンドとの通信

フロントエンドは WebSocket プロトコルでバックエンドとリアルタイムに通信し、次のメッセージタイプに対応しています。

クライアントからの送信：

USER_TEXT_INPUT - ユーザーのテキスト入力
INTERRUPT_TURN - 現在の対話を中断
TOGGLE_ASR_LISTENING - 音声認識の切り替え

サーバーからの応答：

LLM_CHUNK - LLM のストリーミング応答の断片
TTS_STATUS - TTS 再生状態の更新
TOOL_CALL_START/RESULT - ツール呼び出しの過程
SYSTEM_STATUS - システム状態の更新

⚙️ 主な設定

Next.js の設定（`next.config.mjs`）

const nextConfig = {
  eslint: { ignoreDuringBuilds: true },
  typescript: { ignoreBuildErrors: true },
  images: { unoptimized: true },
}

TailwindCSS の設定（`tailwind.config.ts`）

ダークモードの切り替えに対応
shadcn/ui のテーマ変数
レスポンシブのブレークポイント設定
カスタムアニメーション効果

🎨 主なコンポーネント

コアコンポーネント

AppStateProvider：状態の一元管理、WebSocket 接続の管理
ChatInterface：チャット画面、メッセージの表示と入力処理
Sphere：3D による状態の可視化、Three.js による動的エフェクト
LanguageSwitcher：言語の切り替え、国際化対応

UI コンポーネントライブラリ

shadcn/ui をベースにした完全なコンポーネントシステム：

Button、Input、Dialog、Toast などの基本コンポーネント
ScrollArea、Card、Separator などのレイアウトコンポーネント
完全にカスタマイズ可能なテーマシステム

🔧 開発ガイド

新しいコンポーネントの追加

components/ ディレクトリにコンポーネントファイルを作成します。
TypeScript で型を定義します。
shadcn/ui のデザイン規約に従います。
適切なテストとドキュメントを追加します。

状態管理

useAppState フックでグローバル状態にアクセスします。
dispatch 関数で状態を更新します。
状態の不変性の原則を守ります。

スタイルの開発

TailwindCSS のユーティリティクラスを使用します。
CSS 変数でテーマの切り替えに対応します。
レスポンシブデザインの原則に従います。

🛠️ トラブルシューティング

よくある問題

WebSocket の接続に失敗する

バックエンドサービスが起動しているか確認してください。
WebSocket の URL 設定が正しいか確認してください。

3D レンダリングの問題

ブラウザが WebGL に対応しているか確認してください。
ハードウェアアクセラレーションの設定を確認してください。

スタイルの問題

ブラウザのキャッシュをクリアしてください。
TailwindCSS の設定を確認してください。

💡 ヘルプ

問題が発生した場合は 目的に応じて、対応する詳細ドキュメントを参照してください。

🏗️ システムアーキテクチャを理解する → フロントエンドのアーキテクチャ詳解
🔗 WebSocket との連携 → 通信統合ドキュメント
🎨 UI コンポーネントの開発 → コンポーネントシステムのドキュメント
⚡ 状態管理の最適化 → 状態管理のドキュメント
🌍 多言語対応 → 国際化システムのドキュメント

ASR-LLM-TTS 音声対話アシスタント フロントエンド