architecture

Core Modules and Components of Lobe Chat: Architecture and Implementation Guide

March 3, 2026 lobehub/lobe-chat ↗

Lobe Chat is built as a modular monorepo comprising nine core modules—including UI and routing, Zustand state management, agent runtime, context engine, memory management, web crawler, utilities, and backend API layers—that together provide its AI agent capabilities.

Lobe Chat, maintained by lobehub, is a modern AI chat application structured as a modular monorepo. Understanding the core modules and components of Lobe Chat is essential for developers extending its functionality or integrating custom AI agents. The architecture cleanly separates the React frontend, global Zustand stores, and specialized packages for agent execution and context management.

Overview of the Architecture

Lobe Chat follows a monorepo structure where concerns are split between the Next.js frontend application and discrete packages handling specific AI capabilities. The architecture emphasizes modularity, allowing developers to swap implementations—such as changing the web crawler provider or adding new agent types—without affecting the core UI layer.

Core Modules and Components

UI and Routing Layer

The frontend is built on Next.js (App Router) and React, handling app layout, page routes, and feature components. The entry point src/app/layout.tsx builds the root UI with global providers, theme handling, and hot-key management. Specific features like the user panel, skill store, and chat interface are organized under src/features/**, while page routes are defined in src/routes/**.

State Management (Zustand Stores)

Global client state is managed through Zustand stores, organized as composable slices. Key stores include:

src/store/user/store.ts – User profile, authentication, and settings
src/store/tool/store.ts – Tool and plugin registry management
src/store/video/store.ts – Video generation state

These stores provide selectors and actions that UI components consume to maintain synchronized application state.

Agent Runtime (`packages/agent-runtime`)

The Agent Runtime is the core execution engine located in packages/agent-runtime that orchestrates AI agent interactions. It handles conversation flow through GeneralChatAgent.ts, manages usage counting for billing, performs security audits, and coordinates multi-agent workflows. The runtime core logic resides in packages/agent-runtime/src/core/runtime.ts, abstracting LLM provider differences while providing a unified interface for agent execution.

Context Engine (`packages/context-engine`)

The Context Engine in packages/context-engine manages what information gets injected into the LLM context window. It aggregates system prompts through providers like SystemRoleInjector.ts and ToolSystemRole.ts, combines them with user memory, and incorporates knowledge base snippets. This ensures the AI agent receives properly formatted context including system roles, available tools, and relevant user history.

Memory and User Data (`packages/memory-user-memory`)

This module provides types and helpers for persisting user-specific information. Defined in packages/memory-user-memory/src/types.ts, it handles message history, conversation topics, user preferences, and memory retrieval interfaces for the context engine.

Web Crawler (`packages/web-crawler`)

The Web Crawler module in packages/web-crawler fetches external web content and converts it to markdown for agent consumption. It supports multiple provider implementations including Tavily, Firecrawl, and Jina, located in files like packages/web-crawler/src/crawImpl/tavily.ts. The core crawler logic resides in packages/web-crawler/src/crawler.ts, enabling agents to reference live web data in conversations.

Utility Libraries (`packages/utils`)

Shared utilities used across the monorepo include UUID generation in packages/utils/src/uuid.ts, URL parsing in packages/utils/src/url.ts, and token counting helpers.

Backend API Layer

The backend exposes REST and tRPC endpoints through Next.js route handlers under src/app/(backend)/webapi. Key endpoints include src/app/(backend)/webapi/chat/[provider]/route.ts for chat streaming and src/app/(backend)/webapi/models/[provider]/route.ts for model management. These handlers instantiate the agent runtime and manage streaming responses to clients.

How the Components Interact

The architecture follows a clear data flow from user interaction to AI response:

Entry and Layout: src/app/layout.tsx initializes the root UI with global providers and theme handling.
Routing and Features: Pages under src/routes/ import UI widgets from src/features/, which read from global Zustand stores.
State Management: Components interact with stores like useUserStore and useToolStore to access user profiles, settings, and plugin registries.
Chat Initialization: When a user sends a message, the frontend calls the chat API endpoint at src/app/(backend)/webapi/chat/[provider]/route.ts.
Runtime Execution: The backend handler instantiates GeneralChatAgent from packages/agent-runtime, which orchestrates the conversation flow.
Context Injection: The runtime queries the context engine (SystemRoleInjector, ToolSystemRole) to gather system prompts, user memory, and tool definitions.
External Data: If the agent needs web content, the web-crawler module fetches and sanitizes the page into markdown, which is passed as a knowledge chunk.
Streaming Response: The agent streams responses back to the client while the usage counter in agent-runtime records token usage for billing and limits.

Practical Code Examples

Reading Global State in Components

Access user settings through the Zustand store:

import { useUserStore } from '@/store/user';
import { currentSettings } from '@/store/user/slices/settings/selectors';

export default function SettingsPanel() {
  const settings = useUserStore(currentSettings);
  return <pre>{JSON.stringify(settings, null, 2)}</pre>;
}

Relevant source: src/store/user/store.ts – https://github.com/lobehub/lobe-chat/blob/canary/src/store/user/store.ts

Invoking the General Chat Agent

Backend route handler instantiating the runtime:

// src/app/(backend)/webapi/chat/openai/route.ts
import { GeneralChatAgent } from 'agent-runtime';
import { getUserMemoryStoreState } from '@/store/userMemory/store';
import { createContext } from '@/store/context';

export async function POST(req: Request) {
  const { messages, provider } = await req.json();

  const runtime = new GeneralChatAgent({
    provider,
    getUserMemory: () => getUserMemoryStoreState(),
    context: createContext(),
  });

  return runtime.streamResponse(messages);
}

Implementation details: packages/agent-runtime/src/agents/GeneralChatAgent.ts – https://github.com/lobehub/lobe-chat/blob/canary/packages/agent-runtime/src/agents/GeneralChatAgent.ts

Registering Custom Plugins

Adding functionality to the tool store:

// src/store/tool/slices/customPlugin/action.ts
export const createCustomPluginSlice = (set, get) => ({
  addCustomPlugin: (plugin) =>
    set((state) => ({
      customPlugin: {
        ...state.customPlugin,
        list: [...state.customPlugin.list, plugin],
      },
    })),
});

Relevant source: src/store/tool/slices/customPlugin/action.ts – https://github.com/lobehub/lobe-chat/blob/canary/src/store/tool/slices/customPlugin/action.ts

Fetching External Content

Using the web crawler module:

import { crawl } from 'web-crawler';

await crawl('https://example.com', { provider: 'tavily' })
  .then((markdown) => console.log(markdown));

Example script: packages/web-crawler/examples/tools-calling.ts – https://github.com/lobehub/lobe-chat/blob/canary/packages/web-crawler/examples/tools-calling.ts

Summary

Lobe Chat's architecture demonstrates a clean separation of concerns across nine primary modules:

UI and Routing: Next.js App Router implementation in src/app/ and src/routes/
State Management: Zustand stores located in src/store/ for user data, tools, and video generation
Agent Runtime: Core execution engine in packages/agent-runtime featuring GeneralChatAgent
Context Engine: Prompt injection system in packages/context-engine with SystemRoleInjector
Memory Management: User data persistence in packages/memory-user-memory
Web Crawler: External content fetching in packages/web-crawler supporting multiple providers
Utilities: Shared helpers in packages/utils for UUID generation and URL parsing
Backend API: Next.js route handlers in src/app/(backend)/webapi/ for chat streaming and model management

Frequently Asked Questions

What is the Agent Runtime in Lobe Chat?

The Agent Runtime is the core execution engine located in packages/agent-runtime that orchestrates AI agent interactions. It handles conversation flow through GeneralChatAgent.ts, manages usage counting for billing, performs security audits, and coordinates multi-agent workflows. The runtime abstracts LLM provider differences while providing a unified interface for agent execution.

How does Lobe Chat manage global state?

Lobe Chat uses Zustand for global state management, organizing state into modular stores under src/store/. The architecture employs composable slices—such as src/store/user/store.ts for user profiles and src/store/tool/store.ts for plugin registries. Components access these stores through hooks and selectors, ensuring type-safe state access across the application.

What is the purpose of the Context Engine?

How does the Web Crawler module work?

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}

Ask your agent:

"Use Instagit MCP to understand how lobehub/lobe-chat works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →