mirror of
https://github.com/lobehub/lobehub.git
synced 2026-09-20 04:56:13 +08:00
YuTengjing
191f3fe776
* 📝 docs: fix outdated content across the docs site Audited docs/ against the current codebase and fixed stale content that drifted after major refactors (Clerk/NextAuth → Better Auth, src/server → apps/server, src/{config,envs,locales} → packages/*, model-bank updates). - self-hosting/auth: mark removed NextAuth/Clerk pages with deprecation warnings; fix microsoft/zitadel alias claims and the Logto callback path - environment-variables & advanced: correct wrong defaults (S3_SET_ACL, AI_IMAGE_DEFAULT_IMAGE_NUM, index/proxy URLs), drop non-existent env vars and fictional feature flags, fix OIDC config guidance - development: update refactored paths, Better Auth, .mjs configs, remove the MSW section (msw is not a dependency) - providers & model examples: replace retired model ids with in-bank ones; fix comfyui frontmatter corruption - usage: rename Moderator→Orchestrator, GTD→Task, correct shortcut keys, channel capability tables, Feishu/Lark WebSocket mode - platform/migration: fix dead links, docker service name, npx/npm → bun EN and zh-CN pairs updated together. * 📝 docs: fix Logto callback path and AUTH_SECRET deprecation guidance - Revert Logto/Sealos callback URLs to /api/auth/callback/logto to match the runtime SSO redirectURI override - Narrow legacy auth Callout: AUTH_SECRET remains required for Better Auth; mark NEXT_AUTH_SECRET as deprecated in zh-CN * 📝 docs: refresh agent skills for locales, env, auth, and agentRun paths Align OSS agent guidance with post-refactor layout: - packages/locales/src/default + bun run i18n - packages/env/src for env schemas (@/envs alias) - spa-auth shell + src/routes/auth segments - chat agentRun/transports/hetero instead of aiChat * 📝 docs: document APP_URL as required for Better Auth base URL Self-hosted auth uses appEnv.APP_URL as baseURL, not request-header auto-detection. NEXT_PUBLIC_AUTH_URL remains deprecated. * 📝 docs: note self-host search provider setup for web search Built-in lobe-web-browsing needs no client plugin, but self-hosted servers still require SEARCH_PROVIDERS / SEARXNG_URL (default SearXNG). * 📝 docs: point feature guide welcome UI at AgentHome Opening message/questions on the agent chat page live in src/features/AgentHome, not Onboarding WelcomeMessage.
151 lines
7.3 KiB
Plaintext
151 lines
7.3 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.
|
|
|
|
| Router | Use Case | Location |
|
|
| ---------------------- | ------------------------------- | -------------------------- |
|
|
| **Next.js App Router** | Auth pages, SSR, static routes | `src/app/(backend)/` |
|
|
| **React Router DOM** | Main chat SPA, agent interfaces | `src/spa/` + `src/routes/` |
|
|
|
|
**Why hybrid?** SSR delivers auth page security, SEO, and static page performance; SPA delivers instant navigation and reactive state for interactive chat and agent interfaces — the best of both worlds.
|
|
|
|
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
|
|
|
|
**Component priority** when building UI: project components (`src/components/`) → `@lobehub/ui` → Ant Design (`antd`). Always prefer project-level components for consistency.
|
|
|
|
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** (`apps/server/src/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."
|
|
|
|
**Agent execution flow:**
|
|
|
|
1. Parse user input
|
|
2. LLM decides: respond directly or use a tool
|
|
3. Execute tools (single or batch)
|
|
4. Human-in-the-loop approval (if needed)
|
|
5. Feed results back to LLM
|
|
6. Loop until final response is produced
|
|
|
|
## 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
|
|
|
|
## Performance Optimizations
|
|
|
|
- **Code splitting**: Route-based chunking keeps initial bundle size small
|
|
- **Lazy loading**: Heavy components and routes load on demand
|
|
- **SWR caching**: Client-side data is cached and revalidated in the background
|
|
- **Edge caching**: Static and CDN-cacheable responses are edge-distributed
|
|
- **Streaming**: Chat responses stream incrementally via SSE for perceived speed
|
|
- **Virtualization**: Long message lists and agent lists use virtual scroll
|
|
|
|
## Security Measures
|
|
|
|
- **CSRF protection**: SameSite cookies and token validation
|
|
- **XSS prevention**: Content Security Policy headers and output sanitization
|
|
- **Rate limiting**: API rate limits enforced at the edge
|
|
- **SSRF prevention**: Outbound request allowlisting for plugin and MCP calls
|
|
- **SQL injection prevention**: Parameterized queries via Drizzle ORM
|
|
- **Secret management**: API keys and credentials stored as environment variables, never in code or client bundles
|
|
|
|
## 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
|