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 で実装した動的な状態表示用の球体
🌍 国際化対応：中国語・英語の切り替え
⚡ ストリーミング体験：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 コンポーネントを開発する → コンポーネントシステムドキュメント
⚡ 状態管理を最適化する → 状態管理ドキュメント
🌍 多言語に対応する → 国際化システムドキュメント