@lobehub/lobehub 2.0.0-next.173 → 2.0.0-next.175

package/.cursor/rules/db-migrations.mdc

@@ -5,20 +5,26 @@ alwaysApply: false
 
 # Database Migrations Guide
 
-## Step1: Generate migrations:
+## Step1: Generate migrations
 
 ```bash
 bun run db:generate
 ```
 
-this step will generate or update the following files:
+this step will generate following files:
+
+- packages/database/migrations/0046_meaningless_file_name.sql
+- packages/database/migrations/0046_meaningless_file_name.sql
+
+and update the following files:
 
-- packages/database/migrations/0046_xxx.sql
 - packages/database/migrations/meta/\_journal.json
+- packages/database/src/core/migrations.json
+- docs/development/database-schema.dbml
 
 ## Step2: optimize the migration sql fileName
 
-the migration sql file name is randomly generated, we need to optimize the file name to make it more readable and meaningful. For example, `0046_xxx.sql` -> `0046_better_auth.sql`
+the migration sql file name is randomly generated, we need to optimize the file name to make it more readable and meaningful. For example, `0046_meaningless_file_name.sql` -> `0046_user_add_avatar_column.sql`
 
 ## Step3: Defensive Programming - Use Idempotent Clauses
 

package/.cursor/rules/drizzle-schema-style-guide.mdc

@@ -1,8 +1,9 @@
 ---
-description: 
+description:
 globs: src/database/schemas/*
 alwaysApply: false
 ---
+
 # Drizzle ORM Schema Style Guide for lobe-chat
 
 This document outlines the conventions and best practices for defining PostgreSQL Drizzle ORM schemas within the lobe-chat project.
@@ -16,7 +17,8 @@ This document outlines the conventions and best practices for defining PostgreSQ
 
 ## Helper Functions
 
-Commonly used column definitions, especially for timestamps, are centralized in [src/database/schemas/_helpers.ts](mdc:src/database/schemas/_helpers.ts):
+Commonly used column definitions, especially for timestamps, are centralized in [src/database/schemas/\_helpers.ts](mdc:src/database/schemas/_helpers.ts):
+
 - `timestamptz(name: string)`: Creates a timestamp column with timezone
 - `createdAt()`, `updatedAt()`, `accessedAt()`: Helper functions for standard timestamp columns
 - `timestamps`: An object `{ createdAt, updatedAt, accessedAt }` for easy inclusion in table definitions
@@ -29,6 +31,7 @@ Commonly used column definitions, especially for timestamps, are centralized in
 ## Column Definitions
 
 ### Primary Keys (PKs)
+
 - Typically `text('id')` (or `varchar('id')` for some OIDC tables)
 - Often use `.$defaultFn(() => idGenerator('table_name'))` for automatic ID generation with meaningful prefixes
 - **ID Prefix Purpose**: Makes it easy for users and developers to distinguish different entity types at a glance
@@ -36,24 +39,29 @@ Commonly used column definitions, especially for timestamps, are centralized in
 - Composite PKs are defined using `primaryKey({ columns: [t.colA, t.colB] })`
 
 ### Foreign Keys (FKs)
+
 - Defined using `.references(() => otherTable.id, { onDelete: 'cascade' | 'set null' | 'no action' })`
 - FK columns are usually named `related_table_singular_name_id` (e.g., `user_id` references `users.id`)
 - Most tables include a `user_id` column referencing `users.id` with `onDelete: 'cascade'`
 
 ### Timestamps
-- Consistently use the `...timestamps` spread from [_helpers.ts](mdc:src/database/schemas/_helpers.ts) for `created_at`, `updated_at`, and `accessed_at` columns
+
+- Consistently use the `...timestamps` spread from [\_helpers.ts](mdc:src/database/schemas/_helpers.ts) for `created_at`, `updated_at`, and `accessed_at` columns
 
 ### Default Values
+
 - `.$defaultFn(() => expression)` for dynamic defaults (e.g., `idGenerator()`, `randomSlug()`)
 - `.default(staticValue)` for static defaults (e.g., `boolean('enabled').default(true)`)
 
 ### Indexes
+
 - Defined in the table's second argument: `pgTable('name', {...columns}, (t) => ({ indexName: indexType().on(...) }))`
 - Use `uniqueIndex()` for unique constraints and `index()` for non-unique indexes
 - Naming pattern: `table_name_column(s)_idx` or `table_name_column(s)_unique`
 - Many tables feature a `clientId: text('client_id')` column, often part of a composite unique index with `user_id`
 
 ### Data Types
+
 - Common types: `text`, `varchar`, `jsonb`, `boolean`, `integer`, `uuid`, `pgTable`
 - For `jsonb` fields, specify the TypeScript type using `.$type<MyType>()` for better type safety
 
@@ -97,9 +105,7 @@ export const agents = pgTable(
     ...timestamps,
   },
   // return array instead of object, the object style is deprecated
-  (t) => [
-    uniqueIndex('client_id_user_id_unique').on(t.clientId, t.userId),
-  ],
+  (t) => [uniqueIndex('client_id_user_id_unique').on(t.clientId, t.userId)],
 );
 
 export const insertAgentSchema = createInsertSchema(agents);
@@ -110,6 +116,7 @@ export type AgentItem = typeof agents.$inferSelect;
 ## Common Patterns
 
 ### 1. userId + clientId Pattern (Legacy)
+
 Some existing tables include both fields for different purposes:
 
 ```typescript
@@ -129,6 +136,7 @@ clientIdUnique: uniqueIndex('agents_client_id_user_id_unique').on(t.clientId, t.
 - **Note**: This pattern is being phased out for new features to simplify the schema
 
 ### 2. Junction Tables (Many-to-Many Relationships)
+
 Use composite primary keys for relationship tables:
 
 ```typescript
@@ -136,21 +144,26 @@ Use composite primary keys for relationship tables:
 export const agentsKnowledgeBases = pgTable(
   'agents_knowledge_bases',
   {
-    agentId: text('agent_id').references(() => agents.id, { onDelete: 'cascade' }).notNull(),
-    knowledgeBaseId: text('knowledge_base_id').references(() => knowledgeBases.id, { onDelete: 'cascade' }).notNull(),
-    userId: text('user_id').references(() => users.id, { onDelete: 'cascade' }).notNull(),
+    agentId: text('agent_id')
+      .references(() => agents.id, { onDelete: 'cascade' })
+      .notNull(),
+    knowledgeBaseId: text('knowledge_base_id')
+      .references(() => knowledgeBases.id, { onDelete: 'cascade' })
+      .notNull(),
+    userId: text('user_id')
+      .references(() => users.id, { onDelete: 'cascade' })
+      .notNull(),
     enabled: boolean('enabled').default(true),
     ...timestamps,
   },
-  (t) => [
-    primaryKey({ columns: [t.agentId, t.knowledgeBaseId] }),
-  ],
+  (t) => [primaryKey({ columns: [t.agentId, t.knowledgeBaseId] })],
 );
 ```
 
 **Pattern**: `{entity1}Id` + `{entity2}Id` as composite PK, plus `userId` for ownership
 
 ### 3. OIDC Tables Special Patterns
+
 OIDC tables use `varchar` IDs instead of `text` with custom generators:
 
 ```typescript
@@ -166,6 +179,7 @@ export const oidcAuthorizationCodes = pgTable('oidc_authorization_codes', {
 **Reason**: OIDC standards expect specific ID formats and lengths
 
 ### 4. File Processing with Async Tasks
+
 File-related tables reference async task IDs for background processing:
 
 ```typescript
@@ -173,17 +187,21 @@ File-related tables reference async task IDs for background processing:
 export const files = pgTable('files', {
   // ... other fields
   chunkTaskId: uuid('chunk_task_id').references(() => asyncTasks.id, { onDelete: 'set null' }),
-  embeddingTaskId: uuid('embedding_task_id').references(() => asyncTasks.id, { onDelete: 'set null' }),
+  embeddingTaskId: uuid('embedding_task_id').references(() => asyncTasks.id, {
+    onDelete: 'set null',
+  }),
   // ...
 });
 ```
 
-**Purpose**: 
+**Purpose**:
+
 - Track file chunking progress (breaking files into smaller pieces)
 - Track embedding generation progress (converting text to vectors)
 - Allow querying task status and handling failures
 
 ### 5. Slug Pattern (Legacy)
+
 Some entities include auto-generated slugs - this is legacy code:
 
 ```typescript
@@ -195,8 +213,6 @@ slug: varchar('slug', { length: 100 })
 slugUserIdUnique: uniqueIndex('slug_user_id_unique').on(t.slug, t.userId),
 ```
 
-**Current usage**: Only used to identify default agents/sessions (legacy pattern)
-**Future refactor**: Will likely be replaced with `isDefault: boolean()` field
-**Note**: Avoid using slugs for new features - prefer explicit boolean flags for status tracking
+**Current usage**: Only used to identify default agents/sessions (legacy pattern) **Future refactor**: Will likely be replaced with `isDefault: boolean()` field **Note**: Avoid using slugs for new features - prefer explicit boolean flags for status tracking
 
 By following these guidelines, maintain consistency, type safety, and maintainability across database schema definitions.

package/.cursor/rules/hotkey.mdc

@@ -0,0 +1,161 @@
+---
+alwaysApply: false
+---
+# 如何添加新的快捷键：开发者指南
+
+本指南将带您一步步地向 LobeChat 添加一个新的快捷键功能。我们将通过一个完整示例，演示从定义到实现的整个过程。
+
+## 示例场景
+
+假设我们要添加一个新的快捷键功能：**快速清空聊天记录**，快捷键为 `Mod+Shift+Backspace`。
+
+## 步骤 1：更新快捷键常量定义
+
+首先，在 `src/types/hotkey.ts` 中更新 `HotkeyEnum`：
+
+```typescript
+export const HotkeyEnum = {
+  // 已有的快捷键...
+  AddUserMessage: 'addUserMessage',
+  EditMessage: 'editMessage',
+
+  // 新增快捷键
+  ClearChat: 'clearChat', // 添加这一行
+
+  // 其他已有快捷键...
+} as const;
+```
+
+## 步骤 2：注册默认快捷键
+
+在 `src/const/hotkeys.ts` 中添加快捷键的默认配置：
+
+```typescript
+import { KeyMapEnum as Key, combineKeys } from '@lobehub/ui';
+
+// ...现有代码
+
+export const HOTKEYS_REGISTRATION: HotkeyRegistration = [
+  // 现有的快捷键配置...
+
+  // 添加新的快捷键配置
+  {
+    group: HotkeyGroupEnum.Conversation, // 归类到会话操作组
+    id: HotkeyEnum.ClearChat,
+    keys: combineKeys([Key.Mod, Key.Shift, Key.Backspace]),
+    scopes: [HotkeyScopeEnum.Chat], // 在聊天作用域下生效
+  },
+
+  // 其他现有快捷键...
+];
+```
+
+## 步骤 3：添加国际化翻译
+
+在 `src/locales/default/hotkey.ts` 中添加对应的文本描述：
+
+```typescript
+import { HotkeyI18nTranslations } from '@/types/hotkey';
+
+const hotkey: HotkeyI18nTranslations = {
+  // 现有翻译...
+
+  // 添加新快捷键的翻译
+  clearChat: {
+    desc: '清空当前会话的所有消息记录',
+    title: '清空聊天记录',
+  },
+
+  // 其他现有翻译...
+};
+
+export default hotkey;
+```
+
+如需支持其他语言，还需要在相应的语言文件中添加对应翻译。
+
+## 步骤 4：创建并注册快捷键 Hook
+
+在 `src/hooks/useHotkeys/chatScope.ts` 中添加新的 Hook：
+
+```typescript
+export const useClearChatHotkey = () => {
+  const clearMessages = useChatStore((s) => s.clearMessages);
+  const { t } = useTranslation();
+
+  return useHotkeyById(HotkeyEnum.ClearChat, showConfirm);
+};
+
+// 注册聚合
+
+export const useRegisterChatHotkeys = () => {
+  const { enableScope, disableScope } = useHotkeysContext();
+
+  useOpenChatSettingsHotkey();
+  // ...其他快捷键
+  useClearChatHotkey();
+
+  useEffect(() => {
+    enableScope(HotkeyScopeEnum.Chat);
+    return () => disableScope(HotkeyScopeEnum.Chat);
+  }, []);
+
+  return null;
+};
+```
+
+## 步骤 5：给相应 UI 元素添加 Tooltip 提示（可选）
+
+如果有对应的 UI 按钮，可以添加快捷键提示：
+
+```tsx
+import { DeleteOutlined } from '@ant-design/icons';
+import { Tooltip } from '@lobehub/ui';
+import { Button } from 'antd';
+import { useTranslation } from 'react-i18next';
+
+import { useUserStore } from '@/store/user';
+import { settingsSelectors } from '@/store/user/selectors';
+import { HotkeyEnum } from '@/types/hotkey';
+
+const ClearChatButton = () => {
+  const { t } = useTranslation(['hotkey', 'chat']);
+  const clearChatHotkey = useUserStore(settingsSelectors.getHotkeyById(HotkeyEnum.ClearChat));
+
+  // 获取清空聊天的方法
+  const clearMessages = useChatStore((s) => s.clearMessages);
+
+  return (
+    <Tooltip hotkey={clearChatHotkey} title={t('clearChat.title', { ns: 'hotkey' })}>
+      <Button icon={<DeleteOutlined />} onClick={clearMessages} />
+    </Tooltip>
+  );
+};
+```
+
+## 步骤 6：测试新快捷键
+
+1. 启动开发服务器
+2. 打开聊天页面
+3. 按下设置的快捷键组合（`Cmd+Shift+Backspace` 或 `Ctrl+Shift+Backspace`）
+4. 确认功能正常工作
+5. 检查快捷键设置面板中是否正确显示了新快捷键
+
+## 最佳实践
+
+1. **作用域考虑**：根据功能决定快捷键应属于全局作用域还是聊天作用域
+2. **分组合理**：将快捷键放在合适的功能组中（System/Layout/Conversation）
+3. **冲突检查**：确保新快捷键不会与现有系统、浏览器或应用快捷键冲突
+4. **平台适配**：使用 `Key.Mod` 而非硬编码 `Ctrl` 或 `Cmd`，以适配不同平台
+5. **提供清晰描述**：为快捷键添加明确的标题和描述，帮助用户理解功能
+
+按照以上步骤，您可以轻松地向系统添加新的快捷键功能，提升用户体验。如有特殊需求，如桌面专属快捷键，可以通过 `isDesktop` 标记进行区分处理。
+
+## 常见问题排查
+
+- **快捷键未生效**：检查作用域是否正确，以及是否在 RegisterHotkeys 中调用了对应的 hook
+- **快捷键设置面板未显示**：确认在 HOTKEYS_REGISTRATION 中正确配置了快捷键
+- **快捷键冲突**：在 HotkeyInput 组件中可以检测到冲突，用户会看到警告
+- **功能在某些页面失效**：确认是否注册在了正确的作用域，以及相关页面是否激活了该作用域
+
+通过这些步骤，您可以确保新添加的快捷键功能稳定、可靠且用户友好。

package/.cursor/rules/i18n.mdc

@@ -2,6 +2,7 @@
 globs: *.tsx
 alwaysApply: false
 ---
+
 # LobeChat Internationalization Guide
 
 ## Key Points
@@ -14,7 +15,7 @@ alwaysApply: false
 
 ## Directory Structure
 
-```
+```plaintext
 src/locales/
 ├── default/           # Source language files (zh-CN)
 │   ├── index.ts      # Namespace exports
@@ -176,7 +177,3 @@ export default {
 - Check if the key exists in src/locales/default/namespace.ts
 - Ensure the namespace is correctly imported in the component
 - Ensure new namespaces are exported in src/locales/default/index.ts
-
-- 检查键是否存在于 src/locales/default/namespace.ts 中
-- 确保在组件中正确导入命名空间
-- 确保新命名空间已在 src/locales/default/index.ts 中导出

package/.cursor/rules/project-introduce.mdc

@@ -17,6 +17,7 @@ logo emoji: 🤯
 ## Project Technologies Stack
 
 - Next.js 16
+- implement spa inside nextjs with `react-router-dom`
 - react 19
 - TypeScript
 - `@lobehub/ui`, antd for component framework
@@ -29,8 +30,8 @@ logo emoji: 🤯
 - SWR for data fetch
 - aHooks for react hooks library
 - dayjs for time library
-- lodash-es for utility library
+- es-toolkit for utility library
 - TRPC for type safe backend
-- PGLite for client DB and Neon PostgreSQL for backend DB
+- Neon PostgreSQL for backend DB
 - Drizzle ORM
 - Vitest for testing

package/.cursor/rules/project-structure.mdc

@@ -25,22 +25,23 @@ lobe-chat/
 │   └── zh-CN/
 ├── packages/
 │   ├── agent-runtime/
+│   ├── builtin-agents/
+│   ├── builtin-tool-*/           # builtin tool packages
 │   ├── const/
 │   ├── context-engine/
 │   ├── conversation-flow/
 │   ├── database/
-│   │   ├── src/
-│   │   │   ├── models/
-│   │   │   ├── schemas/
-│   │   │   └── repositories/
+│   │   └── src/
+│   │       ├── models/
+│   │       ├── schemas/
+│   │       └── repositories/
+│   ├── desktop-bridge/
 │   ├── electron-client-ipc/
 │   ├── electron-server-ipc/
 │   ├── fetch-sse/
 │   ├── file-loaders/
-│   ├── memory-extract/
+│   ├── memory-user-memory/
 │   ├── model-bank/
-│   │   └── src/
-│   │       └── aiModels/
 │   ├── model-runtime/
 │   │   └── src/
 │   │       ├── core/
@@ -50,9 +51,6 @@ lobe-chat/
 │   ├── python-interpreter/
 │   ├── ssrf-safe-fetch/
 │   ├── types/
-│   │   └── src/
-│   │       ├── message/
-│   │       └── user/
 │   ├── utils/
 │   └── web-crawler/
 ├── public/
@@ -61,24 +59,25 @@ lobe-chat/
 │   ├── app/
 │   │   ├── (backend)/
 │   │   │   ├── api/
-│   │   │   │   ├── auth/
-│   │   │   │   └── webhooks/
+│   │   │   ├── f/
+│   │   │   ├── market/
 │   │   │   ├── middleware/
 │   │   │   ├── oidc/
 │   │   │   ├── trpc/
 │   │   │   └── webapi/
-│   │   │       ├── chat/
-│   │   │       └── tts/
 │   │   ├── [variants]/
+│   │   │   ├── (auth)/
 │   │   │   ├── (main)/
-│   │   │   │   ├── chat/
-│   │   │   │   └── settings/
-│   │   │   └── @modal/
-│   │   └── manifest.ts
+│   │   │   ├── (mobile)/
+│   │   │   ├── onboarding/
+│   │   │   └── router/
+│   │   └── desktop/
 │   ├── components/
 │   ├── config/
+│   ├── const/
+│   ├── envs/
 │   ├── features/
-│   │   └── ChatInput/
+│   ├── helpers/
 │   ├── hooks/
 │   ├── layout/
 │   │   ├── AuthProvider/
@@ -90,23 +89,23 @@ lobe-chat/
 │   ├── locales/
 │   │   └── default/
 │   ├── server/
+│   │   ├── featureFlags/
+│   │   ├── globalConfig/
 │   │   ├── modules/
 │   │   ├── routers/
 │   │   │   ├── async/
-│   │   │   ├── desktop/
-│   │   │   ├── edge/
-│   │   │   └── lambda/
+│   │   │   ├── lambda/
+│   │   │   ├── mobile/
+│   │   │   └── tools/
 │   │   └── services/
 │   ├── services/
-│   │   ├── user/
-│   │   │   ├── client.ts
-│   │   │   └── server.ts
-│   │   └── message/
 │   ├── store/
 │   │   ├── agent/
 │   │   ├── chat/
 │   │   └── user/
 │   ├── styles/
+│   ├── tools/
+│   ├── types/
 │   └── utils/
 └── package.json
 ```
@@ -116,25 +115,22 @@ lobe-chat/
 - UI Components: `src/components`, `src/features`
 - Global providers: `src/layout`
 - Zustand stores: `src/store`
-- Client Services: `src/services/` cross-platform services
-  - clientDB: `src/services/<domain>/client.ts`
-  - serverDB: `src/services/<domain>/server.ts`
+- Client Services: `src/services/`
 - API Routers:
   - `src/app/(backend)/webapi` (REST)
-  - `src/server/routers/{edge|lambda|async|desktop|tools}` (tRPC)
+  - `src/server/routers/{async|lambda|mobile|tools}` (tRPC)
 - Server:
-  - Services(can access serverDB): `src/server/services` server-used-only services
-  - Modules(can't access db): `src/server/modules` (Server only Third-party Service Module)
+  - Services (can access serverDB): `src/server/services`
+  - Modules (can't access db): `src/server/modules`
+  - Feature Flags: `src/server/featureFlags`
+  - Global Config: `src/server/globalConfig`
 - Database:
   - Schema (Drizzle): `packages/database/src/schemas`
   - Model (CRUD): `packages/database/src/models`
   - Repository (bff-queries): `packages/database/src/repositories`
 - Third-party Integrations: `src/libs` — analytics, oidc etc.
+- Builtin Tools: `src/tools`, `packages/builtin-tool-*`
 
 ## Data Flow Architecture
 
-- **Web with ClientDB**: React UI → Client Service → Direct Model Access → PGLite (Web WASM)
-- **Web with ServerDB**: React UI → Client Service → tRPC Lambda → Server Services → PostgreSQL (Remote)
-- **Desktop**:
-  - Cloud sync disabled: Electron UI → Client Service → tRPC Lambda → Local Server Services → PGLite (Node WASM)
-  - Cloud sync enabled: Electron UI → Client Service → tRPC Lambda → Cloud Server Services → PostgreSQL (Remote)
+React UI → Store Actions → Client Service → TRPC Lambda → Server Services -> DB Model → PostgreSQL (Remote)

package/.cursor/rules/react.mdc

@@ -0,0 +1,155 @@
+---
+description:
+globs: *.tsx
+alwaysApply: false
+---
+
+# React Component Writing Guide
+
+- Use antd-style for complex styles; for simple cases, use the `style` attribute for inline styles
+- Use `Flexbox` and `Center` components from react-layout-kit for flex and centered layouts
+- Component selection priority: src/components > installed component packages > lobe-ui > antd
+- Use selectors to access zustand store data instead of accessing the store directly
+
+## Lobe UI Components
+
+- If unsure how to use `@lobehub/ui` components or what props they accept, search for existing usage in this project instead of guessing. Most components extend antd components with additional props
+- For specific usage, search online. For example, for ActionIcon visit <https://ui.lobehub.com/components/action-icon>
+- Read `node_modules/@lobehub/ui/es/index.js` to see all available components and their props
+
+- General
+  - ActionIcon
+  - ActionIconGroup
+  - Block
+  - Button
+  - Icon
+- Data Display
+  - Accordion
+  - Avatar
+  - Collapse
+  - Empty
+  - FileTypeIcon
+  - FluentEmoji
+  - GroupAvatar
+  - GuideCard
+  - Highlighter
+  - Hotkey
+  - Image
+  - List
+  - Markdown
+  - MaterialFileTypeIcon
+  - Mermaid
+  - Segmented
+  - Skeleton
+  - Snippet
+  - SortableList
+  - Tag
+  - Tooltip
+  - Video
+- Data Entry
+  - AutoComplete
+  - CodeEditor
+  - ColorSwatches
+  - CopyButton
+  - DatePicker
+  - DownloadButton
+  - EditableText
+  - EmojiPicker
+  - Form
+  - FormModal
+  - HotkeyInput
+  - ImageSelect
+  - Input
+  - SearchBar
+  - Select
+  - SliderWithInput
+  - ThemeSwitch
+- Feedback
+  - Alert
+  - Drawer
+  - Modal
+- Layout
+  - DraggablePanel
+  - Footer
+  - Grid
+  - Header
+  - Layout
+  - MaskShadow
+  - ScrollShadow
+- Navigation
+  - Burger
+  - DraggableSideNav
+  - Dropdown
+  - Menu
+  - SideNav
+  - Tabs
+  - Toc
+- Theme
+  - ConfigProvider
+  - FontLoader
+  - ThemeProvider
+- Typography
+  - Text
+
+## Routing Architecture
+
+This project uses a **hybrid routing architecture**: Next.js App Router for static pages + React Router DOM for the main SPA.
+
+### Route Types
+
+```plaintext
++------------------+--------------------------------+--------------------------------+
+|   Route Type     |          Use Case              |        Implementation          |
++------------------+--------------------------------+--------------------------------+
+| Next.js App      | Auth pages (login, signup,     | page.tsx file convention       |
+| Router           | oauth, reset-password, etc.)   | src/app/[variants]/(auth)/     |
++------------------+--------------------------------+--------------------------------+
+| React Router     | Main SPA features              | BrowserRouter + Routes         |
+| DOM              | (chat, discover, settings)     | desktopRouter.config.tsx       |
+|                  |                                | mobileRouter.config.tsx        |
++------------------+--------------------------------+--------------------------------+
+```
+
+### Key Files
+
+- Entry point: `src/app/[variants]/page.tsx` - Routes to Desktop or Mobile based on device
+- Desktop router: `src/app/[variants]/router/desktopRouter.config.tsx`
+- Mobile router: `src/app/[variants]/(mobile)/router/mobileRouter.config.tsx`
+- Router utilities: `src/utils/router.tsx`
+
+### Router Utilities
+
+```tsx
+import { dynamicElement, redirectElement, ErrorBoundary, RouteConfig } from '@/utils/router';
+
+// Lazy load a page component
+element: dynamicElement(() => import('./chat'), 'Desktop > Chat')
+
+// Create a redirect
+element: redirectElement('/settings/profile')
+
+// Error boundary for route
+errorElement: <ErrorBoundary resetPath="/chat" />
+```
+
+### Adding New Routes
+
+1. Add route config to `desktopRouter.config.tsx` or `mobileRouter.config.tsx`
+2. Create page component in the corresponding directory under `(main)/`
+3. Use `dynamicElement()` for lazy loading
+
+### Navigation
+
+```tsx
+// In components - use react-router-dom hooks
+import { useNavigate, useParams } from 'react-router-dom';
+
+const navigate = useNavigate();
+navigate('/chat');
+
+// From stores - use global navigate
+import { useGlobalStore } from '@/store/global';
+
+const navigate = useGlobalStore.getState().navigate;
+navigate?.('/settings');
+```