📝 docs(architecture): add system architecture documentation

- create main architecture document (architecture.md)
- add coding standards documentation (coding-standards.md)
- create source tree documentation (source-tree.md)
- add technology stack documentation (tech-stack.md)
- document system overview, architecture principles and deployment architecture
- detail frontend architecture, backend integration and data flow
- specify coding standards for TypeScript, React and file organization
- describe project directory structure and key file functions

docs/architecture.md

@@ -0,0 +1,110 @@
+# stt-demo 系统架构文档 v4
+
+## 概述
+
+stt-demo 是一个基于 Agora RTC/RTM 的实时语音转文字 Web 应用，支持多语言实时转录和翻译功能。
+
+### 系统目标
+
+- 提供高质量的实时音视频通信
+- 实现准确的语音转文字功能
+- 支持多语言实时翻译
+- 提供友好的用户界面和交互体验
+
+### 架构原则
+
+- **模块化**: 采用管理器模式分离关注点
+- **事件驱动**: 基于事件系统实现松耦合通信
+- **状态集中**: 使用 Redux 管理全局状态
+- **类型安全**: 全面使用 TypeScript
+- **性能优先**: 优化音视频流处理和渲染
+
+## 技术架构
+
+### 前端架构
+
+#### 技术栈
+
+- **框架**: React 18 + TypeScript
+- **状态管理**: Redux Toolkit
+- **构建工具**: Vite
+- **UI组件**: Ant Design
+- **路由**: React Router DOM
+- **国际化**: i18next
+
+#### 核心架构模式
+
+**管理器模式**: 将复杂业务逻辑封装在独立的管理器中
+
+- RtcManager: 音视频通信管理
+- RtmManager: 实时消息管理
+- SttManager: 语音转文字管理
+
+**事件驱动**: 管理器间通过自定义事件系统通信
+**组件分层**: 页面组件 → 业务组件 → 基础组件
+
+### 后端集成架构
+
+#### Agora 服务集成
+
+- **Agora RTC**: 实时音视频通信
+- **Agora RTM**: 实时消息传递
+- **Agora STT**: 语音转文字服务
+
+#### API 设计
+
+- RESTful API 设计
+- Token 认证机制
+- 错误处理标准化
+
+## 数据流架构
+
+### 音视频数据流
+
+```
+麦克风/摄像头 → RTC SDK → 网络传输 → 远端用户
+```
+
+### 语音转文字数据流
+
+```
+音频流 → STT 服务 → 文字结果 → RTM 通道 → 界面显示
+```
+
+### 状态数据流
+
+```
+用户操作 → Redux Action → Reducer → Store → 组件更新
+```
+
+## 部署架构
+
+### 开发环境
+
+- Vite 开发服务器 (端口 8080)
+- 热重载支持
+- TypeScript 类型检查
+
+### 生产环境
+
+- Vite 构建优化
+- 静态资源 CDN
+- 环境变量配置
+
+## 扩展性设计
+
+### 水平扩展
+
+- 组件化设计支持功能模块添加
+- 管理器模式便于新业务逻辑集成
+- 配置驱动支持不同部署环境
+
+### 性能优化
+
+- 音视频流优化处理
+- 虚拟滚动支持大量字幕显示
+- 懒加载优化首屏性能
+
+---
+
+_本文档为架构文档主文件，详细的分片文档请参考 docs/architecture/ 目录_

docs/architecture/coding-standards.md

@@ -0,0 +1,130 @@
+# 编码规范
+
+## TypeScript 规范
+
+### 类型定义
+
+- 使用接口定义数据模型
+- 优先使用 `interface` 而非 `type`
+- 导出类型使用 `export interface`
+
+```typescript
+// 正确
+export interface IUserInfo {
+  userName: string
+  userId: number | string
+}
+
+// 避免
+type UserInfo = {
+  userName: string
+  userId: number | string
+}
+```
+
+### 组件规范
+
+- 使用函数式组件 + Hooks
+- 组件文件使用 `.tsx` 扩展名
+- 组件名使用 PascalCase
+
+```typescript
+// 正确
+export const UserList: React.FC<UserListProps> = ({ data }) => {
+  return <div>{/* 组件内容 */}</div>
+}
+```
+
+### 导入导出规范
+
+- 使用绝对路径导入 (`@/`)
+- 按类型分组导入
+- 默认导出仅用于组件
+
+```typescript
+// 正确
+import React, { useState, useEffect } from "react"
+import { useSelector, useDispatch } from "react-redux"
+import { IUserInfo } from "@/types"
+import { apiGetUserInfo } from "@/common/request"
+```
+
+## React 规范
+
+### Hooks 使用
+
+- 自定义 Hook 以 `use` 开头
+- 复杂逻辑封装为自定义 Hook
+- 避免在循环/条件中使用 Hooks
+
+```typescript
+// 正确
+export const useUserData = (userId: string) => {
+  const [user, setUser] = useState<IUserInfo>()
+
+  useEffect(() => {
+    // 获取用户数据
+  }, [userId])
+
+  return user
+}
+```
+
+### 状态管理
+
+- 全局状态使用 Redux Toolkit
+- 局部状态使用 useState
+- 复杂状态逻辑使用 useReducer
+
+## 文件组织规范
+
+### 目录结构
+
+```
+src/
+├── components/     # 可复用组件
+├── pages/         # 页面组件
+├── manager/       # 业务逻辑管理器
+├── store/         # 状态管理
+├── common/        # 通用工具
+├── types/         # 类型定义
+└── styles/        # 样式文件
+```
+
+### 命名约定
+
+- 文件: kebab-case (`user-list.tsx`)
+- 组件: PascalCase (`UserList`)
+- 变量: camelCase (`userName`)
+- 常量: UPPER_SNAKE_CASE (`MAX_USERS`)
+- 接口: I + PascalCase (`IUserInfo`)
+
+## 代码质量
+
+### 错误处理
+
+- 使用 try-catch 处理异步错误
+- 提供有意义的错误消息
+- 记录错误日志
+
+```typescript
+try {
+  await apiCall()
+} catch (error) {
+  console.error("API调用失败:", error)
+  message.error("操作失败，请重试")
+}
+```
+
+### 性能优化
+
+- 使用 React.memo 优化组件重渲染
+- 使用 useMemo/useCallback 避免不必要的计算
+- 懒加载大型组件
+
+### 可维护性
+
+- 函数不超过50行
+- 组件职责单一
+- 添加必要的注释
+- 删除无用代码

docs/architecture/source-tree.md

@@ -0,0 +1,197 @@
+# 源码结构
+
+## 项目根目录
+
+```
+stt-demo/
+├── .bmad-core/          # BMAD 配置和工具
+├── .claude/             # Claude Code 配置
+├── .git/                # Git 版本控制
+├── docs/                # 项目文档
+├── node_modules/        # 依赖包
+├── public/              # 静态资源
+├── src/                 # 源代码
+└── 配置文件...
+```
+
+## 源代码目录结构
+
+### src/ - 主要源代码
+
+```
+src/
+├── components/          # 可复用 UI 组件
+│   ├── avatar/         # 用户头像组件
+│   │   └── index.tsx
+│   ├── caption/        # 字幕相关组件
+│   │   ├── caption-item/
+│   │   └── index.tsx
+│   ├── center-area/    # 主视频区域
+│   │   └── index.tsx
+│   ├── dialog/         # 对话框组件
+│   │   ├── language-setting/
+│   │   ├── language-show/
+│   │   └── language-storage/
+│   ├── extend-message/ # 扩展消息
+│   │   └── index.tsx
+│   ├── footer/         # 底部控制栏
+│   │   ├── caption-popover/
+│   │   └── index.tsx
+│   ├── header/         # 顶部导航
+│   │   └── index.tsx
+│   ├── icons/          # 图标组件
+│   ├── menu/           # 侧边菜单
+│   ├── stream-player/  # 视频流播放器
+│   └── user-list/      # 用户列表
+├── pages/              # 页面组件
+│   ├── 404/           # 404 页面
+│   ├── home/          # 主页面
+│   │   ├── index.module.scss
+│   │   └── index.tsx
+│   └── login/         # 登录页面
+│       ├── index.module.scss
+│       └── index.tsx
+├── manager/            # 业务逻辑管理器
+│   ├── events.ts      # 事件系统
+│   ├── index.ts       # 管理器导出
+│   ├── parser/        # 数据解析器
+│   │   └── index.ts
+│   ├── rtc/           # RTC 管理器
+│   │   ├── index.ts
+│   │   ├── rtc.ts
+│   │   └── types.ts
+│   ├── rtm/           # RTM 管理器
+│   │   ├── index.ts
+│   │   ├── rtm.ts
+│   │   └── types.ts
+│   ├── stt/           # STT 管理器
+│   │   ├── index.ts
+│   │   ├── stt.ts
+│   │   └── types.ts
+│   └── types.ts       # 管理器类型定义
+├── store/             # 状态管理
+│   ├── index.ts       # Store 配置
+│   └── reducers/      # Reducers
+│       └── global.ts  # 全局状态
+├── common/            # 通用工具
+│   ├── constant.ts    # 常量定义
+│   ├── final.ts       # 最终配置
+│   ├── hooks.ts       # 自定义 Hooks
+│   ├── index.ts       # 通用工具导出
+│   ├── mock.ts        # 模拟数据
+│   ├── request.ts     # API 请求
+│   ├── storage.ts     # 本地存储
+│   └── utils.ts       # 工具函数
+├── i18n/              # 国际化
+│   └── index.js       # i18n 配置
+├── router/            # 路由配置
+│   └── index.tsx      # 路由定义
+├── types/             # 类型定义
+│   └── index.ts       # 全局类型
+├── protobuf/          # Protobuf 定义
+│   ├── SttMessage.js  # 编译后的 Protobuf
+│   └── SttMessage.proto
+├── styles/            # 样式文件
+│   ├── global.css     # 全局样式
+│   └── reset.css      # 重置样式
+├── App.tsx            # 根组件
+├── main.tsx           # 应用入口
+└── vite-env.d.ts      # Vite 环境类型
+```
+
+## 关键文件说明
+
+### 应用入口文件
+
+- **`src/main.tsx`**: React 应用启动，配置 Provider
+- **`src/App.tsx`**: 根组件，包含错误处理和屏幕适配
+
+### 核心管理器
+
+- **`src/manager/rtc/rtc.ts`**: RTC 音视频通信管理
+- **`src/manager/rtm/rtm.ts`**: RTM 实时消息管理
+- **`src/manager/stt/stt.ts`**: STT 语音转文字管理
+- **`src/manager/events.ts`**: 自定义事件系统
+
+### 状态管理
+
+- **`src/store/index.ts`**: Redux store 配置
+- **`src/store/reducers/global.ts`**: 全局状态 reducer
+
+### 页面组件
+
+- **`src/pages/login/index.tsx`**: 登录页面
+- **`src/pages/home/index.tsx`**: 主页面（音视频通话）
+
+### 通用工具
+
+- **`src/common/hooks.ts`**: 自定义 React Hooks
+- **`src/common/request.ts`**: API 请求封装
+- **`src/common/utils.ts`**: 工具函数
+- **`src/common/storage.ts`**: 本地存储管理
+
+## 模块依赖关系
+
+### 核心依赖流
+
+```
+App.tsx → Router → Pages → Components
+                    ↓
+                Manager Layer (RTC/RTM/STT)
+                    ↓
+                Store (Redux)
+                    ↓
+                Common Utilities
+```
+
+### 管理器间依赖
+
+```
+RtcManager ──────┐
+                 ├──→ Event System
+RtmManager ──────┤
+                 └──→ Store
+SttManager ──────┘
+```
+
+## 文件命名规范
+
+### 组件文件
+
+- 主文件: `index.tsx`
+- 样式文件: `index.module.scss`
+- 类型文件: `types.ts` (如存在)
+
+### 工具文件
+
+- 工具函数: `utils.ts`
+- 常量定义: `constant.ts`
+- API 接口: `request.ts`
+
+### 导出规范
+
+- 默认导出: 主要用于组件
+- 命名导出: 用于工具函数、类型等
+- Barrel 导出: 使用 `index.ts` 统一导出
+
+## 新增文件指南
+
+### 添加新组件
+
+1. 在 `components/` 下创建新目录
+2. 创建 `index.tsx` 和 `index.module.scss`
+3. 如需类型，创建 `types.ts`
+4. 更新相关 barrel 导出文件
+
+### 添加新页面
+
+1. 在 `pages/` 下创建新目录
+2. 遵循组件文件规范
+3. 在 `src/router/index.tsx` 中添加路由
+
+### 添加新管理器
+
+1. 在 `manager/` 下创建新目录
+2. 实现核心业务逻辑
+3. 定义相关类型
+4. 更新 `manager/index.ts` 导出

docs/architecture/tech-stack.md

@@ -0,0 +1,180 @@
+# 技术栈
+
+## 核心技术
+
+### 前端框架
+
+**React 18.2.0**
+
+- 函数式组件 + Hooks
+- Concurrent Features 支持
+- 严格模式启用
+
+**TypeScript 5.2.2**
+
+- 全面类型安全
+- 严格的类型检查
+- 现代 ES 特性支持
+
+### 状态管理
+
+**Redux Toolkit 1.6.2**
+
+- 简化 Redux 使用
+- Immer 不可变更新
+- RTK Query 准备集成
+
+### 构建工具
+
+**Vite 5.0.8**
+
+- 快速的冷启动
+- 热模块替换 (HMR)
+- 优化的生产构建
+
+### UI 组件库
+
+**Ant Design 5.15.3**
+
+- 企业级设计系统
+- 丰富的组件库
+- 主题定制支持
+
+## Agora 实时服务
+
+### Agora RTC SDK 4.20.0
+
+**功能特性**
+
+- 高质量音视频通信
+- 低延迟流媒体
+- 自适应网络优化
+
+**核心类**
+
+- `IAgoraRTCClient`: RTC 客户端
+- 音视频轨道管理
+- 发布/订阅机制
+
+### Agora RTM 2.1.9
+
+**功能特性**
+
+- 实时消息传递
+- 频道管理
+- 用户状态同步
+
+**核心类**
+
+- RTM 客户端管理
+- 频道消息处理
+- 元数据存储
+
+### Agora STT 服务
+
+**功能特性**
+
+- 实时语音转文字
+- 多语言支持
+- 实时翻译
+
+**API 集成**
+
+- RESTful API 调用
+- Token 认证
+- 任务生命周期管理
+
+## 开发工具链
+
+### 包管理
+
+**npm/yarn**
+
+- 依赖版本锁定
+- 脚本命令管理
+- 工作区支持
+
+### 代码质量
+
+**ESLint**
+
+- 代码规范检查
+- 自动修复支持
+- 自定义规则配置
+
+**Prettier**
+
+- 代码格式化
+- 一致的代码风格
+- 集成 ESLint
+
+### 测试工具
+
+**Vitest** (计划集成)
+
+- 单元测试框架
+- 组件测试支持
+- 覆盖率报告
+
+## 第三方库
+
+### 路由管理
+
+**React Router DOM 6.21.3**
+
+- 声明式路由
+- 懒加载支持
+- 导航守卫
+
+### 国际化
+
+**i18next 23.8.2**
+
+- 多语言支持
+- 动态加载翻译
+- 语言检测
+
+### 工具库
+
+**lodash-es 4.17.21**
+
+- 实用函数库
+- Tree-shaking 优化
+- 类型定义支持
+
+**axios 1.6.7**
+
+- HTTP 客户端
+- 请求拦截器
+- 错误处理
+
+## 环境要求
+
+### 开发环境
+
+- Node.js 18+
+- 现代浏览器 (Chrome 90+, Firefox 88+, Safari 14+)
+- 网络连接 (用于 Agora 服务)
+
+### 生产环境
+
+- 静态文件服务器
+- HTTPS 支持 (Agora 要求)
+- CDN 加速 (可选)
+
+## 版本兼容性
+
+### 浏览器支持
+
+| 浏览器  | 最低版本 | 备注          |
+| ------- | -------- | ------------- |
+| Chrome  | 90       | 完全支持      |
+| Firefox | 88       | 完全支持      |
+| Safari  | 14       | 完全支持      |
+| Edge    | 90       | 基于 Chromium |
+
+### Node.js 支持
+
+- 开发: Node.js 18+
+- 构建: Node.js 16+
+- 运行时: 浏览器环境