---
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