mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-27 13:29:15 +07:00
463d6c8762
* 🔧 chore(vscode): add typescript.tsdk and disable mdx server Fix MDX extension crash caused by Cursor's bundled TypeScript version * 🔧 chore(claude): add skills symlink to .claude directory * 📝 docs: update development guides with current tech stack and architecture - Update tech stack: Next.js 16 + React 19, hybrid routing (App Router + React Router DOM), tRPC, Drizzle ORM + PostgreSQL, react-i18next - Update directory structure to reflect monorepo layout (apps/, packages/, e2e/, locales/) - Expand src/server/ with detailed subdirectory descriptions - Add complete SPA routing architecture with desktop and mobile route tables - Add tRPC router grouping details (lambda, async, tools, mobile) - Add data flow diagram - Simplify dev setup section to link to setup-development guide - Fix i18n default language description (English, not Chinese) - Sync all changes between zh-CN and English versions * 📝 docs: expand data flow diagram in folder structure guide Replace the single-line data flow with a detailed layer-by-layer flow diagram showing each layer's location and responsibility. * 📝 docs: modernize feature development guide - Remove outdated clientDB/pglite/indexDB references - Update schema path to packages/database/src/schemas/ - Update types path to packages/types/src/ - Replace inline migration steps with link to db-migrations guide - Add complete layered architecture table (Client Service, WebAPI, tRPC Router, Server Service, Server Module, Repository, DB Model) - Clarify Client Service as frontend code - Add i18n handling section with workflow and key naming convention - Remove verbose CSS style code, keep core business logic only - Expand testing section with commands, skill refs, and CI tip * 🔥 docs: remove outdated frontend feature development guide Content is superseded by the comprehensive feature-development guide which covers the full chain from schema to testing. * 📝 docs: add LobeHub ecosystem and community resources Add official ecosystem packages (LobeUI, LobeIcons, LobeCharts, LobeEditor, LobeTTS, LobeLint, Lobe i18n, MCP Mark) and community platforms (Agent Market, MCP Market, YouTube, X, Discord). * 📝 docs: improve contributing guidelines and resources - Clarify semantic release triggers (feat/fix vs style/chore) - Add testing section with Vitest/E2E/CI requirements - Update contribution steps to include CI check - Add LobeHub ecosystem packages and community platforms to resources * 📝 docs: rewrite architecture guide to reflect current platform design * 📝 docs: add code quality tools to architecture guide * 📝 docs: rewrite chat-api guide to reflect current architecture - Update sequence diagram with Agent Runtime loop as core execution engine - Replace PluginGateway with ToolExecution layer (Builtin/MCP/Plugin) - Update all path references (model-runtime, agent-runtime, fetch-sse packages) - Split old AgentRuntime section into Model Runtime + Agent Runtime - Add tool calling taxonomy: Builtin, MCP, and Plugin (deprecated) - Add client-side vs server-side execution section - Remove outdated adapter pseudo-code examples * 📝 docs: update file paths in add-new-image-model guide - src/libs/standard-parameters/ → packages/model-bank/src/standard-parameters/ - src/config/aiModels/ → packages/model-bank/src/aiModels/ - src/libs/model-runtime/ → packages/model-runtime/src/providers/ * 📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides The S3_PUBLIC_DOMAIN env var was incorrectly removed from all documentation in commit4a87b31. This variable is still required by the code (src/server/services/file/impls/s3.ts) to generate public URLs for uploaded files. Without it, image URLs sent to vision models are just S3 keys instead of full URLs. Closes #12161 * 📦 chore: pin @lobehub/ui to 4.33.4 to fix SortableList type errors @lobehub/ui 4.34.0 introduced breaking type changes in SortableList where SortableListItem became strict, causing type incompatibility in onChange and renderItem callbacks across 6 files. Pin to 4.33.4 via pnpm overrides to enforce consistent version across monorepo. * 🐛 fix: correct ReadableStream type annotations and add dom.asynciterable - Add dom.asynciterable to tsconfig lib for ReadableStream async iteration - Fix createCallbacksTransformer return type: TransformStream<string, Uint8Array> - Update stream function return types from ReadableStream<string> to ReadableStream<Uint8Array> (llama.ts, ollama.ts, claude.ts) - Remove @ts-ignore from for-await loops in test files - Add explicit string[] type for chunks arrays * Revert "📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides" This reverts commit24073f83d3.
115 lines
5.4 KiB
Plaintext
115 lines
5.4 KiB
Plaintext
---
|
|
title: Architecture Design
|
|
description: >-
|
|
Explore the architecture of LobeHub, an open-source AI Agent platform
|
|
built on Next.js, covering frontend, backend, runtime, and data storage.
|
|
tags:
|
|
- LobeHub
|
|
- Architecture Design
|
|
- Agent Platform
|
|
- Next.js
|
|
---
|
|
|
|
# Architecture Design
|
|
|
|
LobeHub is an open-source AI Agent platform built on Next.js, enabling users to interact with AI through natural language, use tools, manage knowledge bases, and more. The following is an overview of LobeHub's architecture design.
|
|
|
|
## Application Architecture Overview
|
|
|
|
The overall architecture of LobeHub consists of the following core layers:
|
|
|
|
```plaintext
|
|
+---------------------+--------------------------------------------------+
|
|
| Layer | Description |
|
|
+---------------------+--------------------------------------------------+
|
|
| Frontend | Next.js RSC + React Router DOM hybrid SPA |
|
|
| Backend API | RESTful WebAPI + tRPC Routers |
|
|
| Runtime | Model Runtime + Agent Runtime |
|
|
| Auth | Better Auth (email/password + SSO) |
|
|
| Data Storage | PostgreSQL + Redis + S3 |
|
|
| Marketplace | Agent Market + MCP Tool Market |
|
|
+---------------------+--------------------------------------------------+
|
|
```
|
|
|
|
## Frontend Architecture
|
|
|
|
The frontend uses the Next.js framework with a **Next.js RSC + React Router DOM hybrid routing** approach: Next.js App Router handles server-rendered pages (e.g., auth pages), while React Router DOM powers the main SPA.
|
|
|
|
Key tech stack:
|
|
|
|
- **UI Components**: `@lobehub/ui`, antd
|
|
- **CSS-in-JS**: antd-style
|
|
- **State Management**: zustand (slice pattern)
|
|
- **Data Fetching**: SWR + tRPC
|
|
- **i18n**: react-i18next
|
|
|
|
Frontend code is organized by responsibility under `src/`. See [Directory Structure](/docs/development/basic/folder-structure) for details.
|
|
|
|
## Backend API
|
|
|
|
The backend provides two API styles:
|
|
|
|
- **RESTful WebAPI** (`src/app/(backend)/webapi/`): Handles endpoints requiring special processing such as chat streaming, TTS, and file serving
|
|
- **tRPC Routers** (`src/server/routers/`): Type-safe main business routes, grouped by runtime:
|
|
- `lambda/` — Main business (agent, session, message, topic, file, knowledge, settings, etc.)
|
|
- `async/` — Long-running async operations (file processing, image generation, RAG evaluation)
|
|
- `tools/` — Tool invocations (search, MCP, market)
|
|
- `mobile/` — Mobile-specific routes
|
|
|
|
## Runtime
|
|
|
|
### Model Runtime
|
|
|
|
`@lobechat/model-runtime` (`packages/model-runtime/`) is the LLM API adapter layer that normalizes API differences across 30+ AI providers (OpenAI, Anthropic, Google, Bedrock, Ollama, etc.), providing a unified calling interface. Each provider has its own adapter implementation. It is stateless — each call is independent.
|
|
|
|
### Agent Runtime
|
|
|
|
`@lobechat/agent-runtime` (`packages/agent-runtime/`) is the agent orchestration engine that sits above Model Runtime, driving the full lifecycle of multi-step AI agent behavior:
|
|
|
|
- **Plan-Execute Loop**: Core state machine cycling through LLM calls → tool execution → result processing
|
|
- **Tool Invocation & Batch Execution**: Supports single and batch tool calls
|
|
- **Human-in-the-Loop**: Security checks and human approval flows
|
|
- **Context Compression**: Manages context window limits
|
|
- **Usage & Cost Tracking**: Accumulates token usage and monetary costs
|
|
- **Multi-Agent Orchestration**: `GroupOrchestrationRuntime` supports Supervisor + Executor pattern for multi-agent collaboration
|
|
|
|
In short: Model Runtime handles "how to communicate with an LLM provider"; Agent Runtime handles "how to run a complete agent using LLMs, tools, and human approvals."
|
|
|
|
## Authentication
|
|
|
|
LobeHub uses [Better Auth](https://www.better-auth.com/) as the authentication framework, supporting:
|
|
|
|
- Email + password registration and login
|
|
- SSO single sign-on (GitHub, Google, and various OAuth providers)
|
|
|
|
Auth configuration is in `src/auth.ts`, with related routes under `src/app/(backend)/api/`.
|
|
|
|
## Data Storage
|
|
|
|
```plaintext
|
|
+---------------+----------------------------------------------+
|
|
| Storage | Usage |
|
|
+---------------+----------------------------------------------+
|
|
| PostgreSQL | Primary database for users, sessions, |
|
|
| | messages, agent configs, etc. |
|
|
| Redis | Caching, session state, rate limiting |
|
|
| S3 | File storage (uploads, images, knowledge |
|
|
| | base files, etc.) |
|
|
+---------------+----------------------------------------------+
|
|
```
|
|
|
|
Database operations use Drizzle ORM, with schemas defined in `packages/database/src/schemas/`.
|
|
|
|
## Marketplace
|
|
|
|
- **Agent Market**: Provides AI agents for various scenarios; users can discover, use, and share agents
|
|
- **MCP Tool Market**: Discover and integrate MCP tools to extend agent capabilities
|
|
|
|
## Development and Deployment
|
|
|
|
- **Version Control**: Git + GitHub, gitmoji commit conventions
|
|
- **Code Quality**: ESLint, Stylelint, TypeScript type checking, circular dependency detection (dpdm), dead code detection (knip)
|
|
- **Testing**: Vitest unit tests + Cucumber/Playwright E2E tests
|
|
- **CI/CD**: GitHub Actions for automated testing, building, and releasing
|
|
- **Deployment**: Supports Vercel, Docker, and self-hosting on major cloud platforms
|