Overall System Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• apps/desktop/README.md
• src/tools/artifacts/systemRole.ts
• src/tools/local-system/systemRole.ts
• scripts/seedBundledApps/index.ts
• packages/database/src/repositories/dataImporter/tests/fixtures/agentsToSessions.json
• packages/database/src/repositories/dataImporter/deprecated/tests/index.test.ts
• src/server/ld.ts
• packages/prompts/src/chains/summaryDescription.ts
• src/locales/default/discover.ts

LobeChat is a high-performance AI chat application built with a modern technology stack. Its architecture is designed around a monorepo structure, enabling shared packages and streamlined development across its main applications: a primary web interface and a cross-platform desktop application. The system is built to be extensible, with a core focus on configurable "Agents" that can be enhanced with various tools and plugins.

The overall architecture separates the frontend presentation layer (Next.js, React), state management (Zustand, SWR), and the data layer (PostgreSQL with Drizzle ORM). The desktop application extends this by wrapping the web app in Electron, providing deeper OS integration, native features like multi-window management, and enhanced security for local operations.

Sources: AGENTS.md, apps/desktop/README.md

Monorepo and Project Structure

The project utilizes a pnpm-managed monorepo, which organizes the codebase into distinct applications and shared packages. This structure promotes code reuse and modularity.

Sources: AGENTS.md:12-16

The diagram below illustrates the high-level directory structure.

Key directories include:

• apps/: Contains the main, deployable applications, most notably the desktop Electron app.
• packages/: Houses shared libraries and modules like database, prompts, and UI components.
• src/: The main source code for the Next.js web application, containing core logic, state management, and UI components.

Sources: AGENTS.md:19-21, apps/desktop/README.md:118-132

Technology Stack

The project is built using a modern set of technologies chosen for performance, type safety, and developer experience.

Category	Technology	Description
Frontend	Next.js 15, React 19	Core framework for the web application.
UI Components	Ant Design, @lobehub/ui	Provides the building blocks for the user interface.
State Management	Zustand, SWR	Manages application state and data fetching.
Database	PostgreSQL, PGLite, Drizzle ORM	Handles data persistence and querying.
Desktop App	Electron	Framework for the cross-platform desktop application.
Build Tools	Vite, Turbopack (dev), Webpack (prod)	Used for building and bundling the applications.
Testing	Vitest, Testing Library	Ensures code quality and correctness.
Package Manager	pnpm	Manages dependencies within the monorepo.

Sources: AGENTS.md:5-16, apps/desktop/README.md:78-85

Core Data Model

The application's data is centered around the concepts of Agents, Sessions, Messages, and Topics. These entities are interconnected to create the chat experience.

The following Entity-Relationship diagram shows the database schema for these core entities.

• Agents: Represent configurable AI assistants. Each agent has a systemRole, a default model and provider, and specific params that define its behavior.
• Sessions: A chat session is associated with an agent. The agents_to_sessions table links them.
• Topics: Within a session, conversations can be organized into different topics.
• Messages: The individual chat messages within a session and topic. They form a threaded conversation via the parentId.

Sources: packages/database/src/repositories/dataImporter/tests/fixtures/agentsToSessions.json, packages/database/src/repositories/dataImporter/deprecated/tests/index.test.ts:227-248

Bundled Apps

The system includes "Bundled Apps," which are pre-configured agents seeded into the database. These serve as ready-to-use assistants for specific tasks like "Code Reviewer" or "Artifact Creator." Each bundled app defines an agent's complete configuration, including its systemRole, model, provider, and openingMessage.

Sources: scripts/seedBundledApps/index.ts:10-85

Agent and Tool System

Agents are the central actors in LobeChat. Their capabilities are defined by their systemRole prompt and can be extended with tools. The system has built-in support for several advanced tool types.

Artifacts System

The Artifacts system allows an agent to generate substantial, self-contained content that is displayed in a separate UI window. This is used for content that a user might want to modify, reuse, or view in a structured way, such as code, documents, or diagrams.

The agent decides whether to use an artifact based on a set of criteria defined in its system prompt.

Sources: src/tools/artifacts/systemRole.ts:2-17

The following flowchart illustrates the agent's decision-making process for creating an artifact.

The system supports various artifact types, each with a specific MIME type:

Artifact Type	MIME Type	Description
Code	application/lobe.artifacts.code	For code snippets in any language.
Documents	text/markdown	For plain text or Markdown documents.
HTML	text/html	For single-file, renderable HTML pages.
SVG	image/svg+xml	For renderable SVG images.
Mermaid Diagrams	application/lobe.artifacts.mermaid	For Mermaid diagram syntax.
React Components	application/lobe.artifacts.react	For renderable React components with access to recharts and lucide-react.

Sources: src/tools/artifacts/systemRole.ts:31-90

Local File System Tool

For the desktop application, a powerful "Local System" tool is available. This tool grants the agent the ability to interact directly with the user's local file system.

The core capabilities are exposed as a set of functions:

• listLocalFiles: Lists files and directories in a path.
• readLocalFile: Reads the content of a file.
• writeFile: Writes content to a text file.
• searchLocalFiles: Searches for files based on keywords.
• renameLocalFile: Renames a file or directory.
• moveLocalFiles: Moves files or directories.

Sources: src/tools/local-system/systemRole.ts:11-20

The workflow for using this tool is as follows:

1. The user makes a request involving local files.
2. The agent identifies the correct tool to use (e.g., readFile).
3. The agent uses paths from a predefined user_context for common locations like "Desktop" or "Downloads".
4. The agent executes the file operation via the tool call.
5. The results are returned to the user, with file paths formatted inside a special <localFile /> tag.

Sources: src/tools/local-system/systemRole.ts:22-27, 60-65

Desktop Application Architecture

The LobeChat Desktop application is built with Electron and features a sophisticated event-driven architecture designed for robustness and extensibility. It uses a multi-process model, with a main process orchestrating multiple renderer windows (e.g., for chat, settings).

Sources: apps/desktop/README.md:90-93

The architecture is managed by a central App.ts orchestrator that uses a Dependency Injection (IoC) container to manage controllers and services. Communication between the main and renderer processes is handled via type-safe IPC events.

This diagram shows the high-level components of the desktop application's main process.

Key components of this architecture include:

• IoC Container: Manages the lifecycle and dependencies of controllers and services.
• Browser Management: Handles the creation and coordination of multiple windows.
• Window Management: Manages window state, including position, theme, and error handling.
• Infrastructure Services: A collection of managers for handling configuration (StoreManager), internationalization (I18nManager), auto-updates (UpdaterManager), and serving local files (StaticFileServerManager).
• UI System: Integrates with the native OS to provide a system tray, application menus, and global shortcuts.

Sources: apps/desktop/README.md:145-212

SEO and Linked Data (LD+JSON)

The web application generates structured data using the LD+JSON format to improve its visibility and representation on search engines. The Ld class is responsible for creating this data.

Sources: src/server/ld.ts:31-56

The main schema types generated are:

• Organization: Describes LobeHub as the organization behind the application.
• WebSite: Represents the LobeChat website.
• WebPage: Describes individual pages, with properties like title, description, and publication date.
• Article: Used for content that can be considered an article, including author and tags.

The Ld class provides methods to generate these structures.