docs/development/basic/architecture.zh-CN.mdx
LobeHub 是一个基于 Next.js 构建的开源 AI Agent 平台，使用户能够与 AI 进行自然语言交互、使用工具、管理知识库等。以下是 LobeHub 的架构设计概览。
LobeHub 的整体架构由以下核心层组成：
+---------------------+--------------------------------------------------+
| Layer | Description |
+---------------------+--------------------------------------------------+
| Frontend | Next.js RSC + React Router DOM 混合路由 SPA |
| Backend API | RESTful WebAPI + tRPC Routers |
| Runtime | Model Runtime + Agent Runtime |
| Auth | Better Auth（邮箱密码 + SSO） |
| Data Storage | PostgreSQL + Redis + S3 |
| Marketplace | Agent 市场 + MCP 工具市场 |
+---------------------+--------------------------------------------------+
前端采用 Next.js 框架，使用 Next.js RSC + React Router DOM 混合路由方案：Next.js App Router 处理服务端渲染页面（如认证页），React Router DOM 承载主应用 SPA。
| 路由方式 | 使用场景 | 位置 |
|---|---|---|
| Next.js App Router | 认证页、SSR、静态路由 | src/app/(backend)/ |
| React Router DOM | 主聊天 SPA、Agent 界面 | src/spa/ + src/routes/ |
为什么使用混合路由？ SSR 为认证页提供安全性、SEO 和静态页性能；SPA 为交互式聊天和 Agent 界面提供即时导航和响应式状态管理 —— 两者各取所长。
主要技术栈：
@lobehub/ui、antd组件使用优先级：项目组件（src/components/）→ @lobehub/ui → Ant Design（antd）。始终优先使用项目级组件以保持一致性。
前端代码按职责分层在 src/ 目录下，详见 目录架构。
后端提供两种 API 形式：
src/app/(backend)/webapi/）：处理 chat 流式响应、TTS、文件服务等需要特殊处理的端点src/server/routers/）：类型安全的主要业务路由，按运行时分组：
lambda/ — 主业务（agent、session、message、topic、file、knowledge、settings 等）async/ — 耗时异步操作（文件处理、图像生成、RAG 评估）tools/ — 工具调用（search、MCP、market）mobile/ — 移动端专用@lobechat/model-runtime（packages/model-runtime/）是 LLM API 适配层，抹平了 30+ 不同 AI Provider 之间的 API 差异（OpenAI、Anthropic、Google、Bedrock、Ollama 等），提供统一的调用接口。每个 Provider 有独立的适配器实现。它是无状态的，每次调用独立。
@lobechat/agent-runtime（packages/agent-runtime/）是 Agent 编排引擎，位于 Model Runtime 之上，负责驱动多步 AI Agent 行为的完整生命周期：
GroupOrchestrationRuntime 支持 Supervisor + Executor 模式的多 Agent 编排简言之：Model Runtime 解决 "如何与 LLM Provider 通信"，Agent Runtime 解决 "如何运行一个使用 LLM、工具、人工审批的完整 Agent"。
Agent 执行流程：
LobeHub 使用 Better Auth 作为认证框架，支持：
认证配置位于 src/auth.ts，相关路由在 src/app/(backend)/api/ 下。
+---------------+----------------------------------------------+
| Storage | Usage |
+---------------+----------------------------------------------+
| PostgreSQL | 主数据库，存储用户、会话、消息、Agent 配置等 |
| Redis | 缓存、会话状态、速率限制 |
| S3 | 文件存储（用户上传、图片、知识库文件等） |
+---------------+----------------------------------------------+
数据库使用 Drizzle ORM 操作，schema 定义在 packages/database/src/schemas/。