Desktop Application Architecture

Relevant source files

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

• apps/desktop/README.md
• AGENTS.md
• CLAUDE.md
• apps/desktop/README.zh-CN.md
• src/tools/local-system/systemRole.ts
• src/tools/artifacts/systemRole.ts
• scripts/seedBundledApps/index.ts
• src/app/apps/bundled/[id]/page.tsx

The LobeChat Desktop application is a cross-platform client built with Electron. It provides a native desktop experience with features like multi-window management, automatic updates, and deep OS integration. The architecture is designed to be modular and event-driven, leveraging dependency injection for loose coupling and better maintainability. It supports macOS, Windows, and Linux.

The architecture is centered around a main process that orchestrates various managers for handling windows, UI elements, and infrastructure services. Communication between the main and renderer processes is handled via a type-safe IPC system. This design allows for a clean separation of concerns, where business logic is encapsulated in services and event handling is managed by controllers. For more information on specific implementation patterns, see the development rules for desktop features, local tools, and window management.

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

Core Architecture

The application's core is built on Electron, TypeScript, and Vite. It employs a sophisticated structure based on dependency injection (IoC), an event-driven model for inter-process communication (IPC), and dynamic module loading.

Sources: apps/desktop/README.md

Technology Stack

Technology	Version / Standard	Purpose
Electron	37.1.0	Cross-platform desktop framework
Node.js	22+	Backend runtime
TypeScript	5.7+	Type-safe development
Vite	6.2+	Build tooling
Dependency Injection	Custom IoC	Manages services and controllers
Event-Driven	Custom IPC	Communication between processes
electron-builder	-	Application packaging and building
electron-updater	-	Automatic update mechanism
electron-store	-	Persistent configuration storage

Sources: apps/desktop/README.md

Core Directory Structure

The main process source code is organized into a modular structure that separates concerns into different managers and services.

src/main/core/
├── App.ts                    # 🎯 Main application orchestrator
├── IoCContainer.ts           # 🔌 Dependency injection container
├── window/                   # 🪟 Window management modules
│   ├── WindowThemeManager.ts     # 🎨 Theme synchronization
│   ├── WindowPositionManager.ts  # 📐 Position persistence
│   └── ...
├── browser/                  # 🌐 Browser management modules
│   ├── Browser.ts               # 🪟 Individual window instances
│   └── BrowserManager.ts        # 👥 Multi-window coordinator
├── ui/                       # 🎨 UI system modules
│   ├── TrayManager.ts           # 🔧 Tray management
│   ├── MenuManager.ts           # 📋 Native menu system
│   └── ShortcutManager.ts       # ⌨️  Global shortcuts
└── infrastructure/           # 🔧 Infrastructure services
    ├── StoreManager.ts          # 💾 Configuration storage
    ├── I18nManager.ts           # 🌍 Internationalization
    ├── UpdaterManager.ts        # 📦 Auto-update system
    └── StaticFileServerManager.ts # 🗂️ Local file serving

This diagram illustrates the high-level components of the desktop application.

Application Lifecycle

The App.ts class is the central orchestrator, managing the application's lifecycle from initialization to shutdown. The process is divided into two main phases: Initialization and Bootstrap.

Sources: apps/desktop/README.md

1. Initialization Phase

During this phase, the application sets up its foundational components.

1. System Information Logging: Captures and logs OS, CPU, RAM, and locale details for debugging.
2. Store Manager Setup: Initializes electron-store for persistent configuration.
3. Dynamic Module Loading: Automatically discovers and loads all controller and service modules.
4. IPC Event Registration: Sets up listeners for inter-process communication channels.

Sources: apps/desktop/README.md

2. Bootstrap Phase

After initialization, the application bootstraps its core services and UI.

1. Single Instance Check: Ensures only one instance of the application is running.
2. IPC Server Launch: Starts the communication server to handle events from renderer processes.
3. Core Manager Initialization: Sequentially starts all managers, including I18n, Menu, Static File Server, Shortcuts, Browser Windows, System Tray, and the Auto-Updater.

The following diagram shows the application startup flow.

Dependency Injection and Event System

The architecture heavily relies on a custom Dependency Injection (IoC) container and an event-driven system for communication.

Sources: apps/desktop/README.md

IoC Container

The IoC container, defined in IoCContainer.ts, uses a WeakMap to manage decorated controller methods. This allows for automatic registration and retrieval of services and controllers in a type-safe manner.

Sources: apps/desktop/README.md

Event-Driven IPC

Inter-process communication is managed through an event-driven system. Controllers use decorators like @ipcClientEvent and @ipcServerEvent to register methods that handle specific IPC events.

• @ipcClientEvent: Registers a method to handle an event sent from a renderer process (the client).
• @ipcServerEvent: Registers a method to handle an event originating from the main process (the server).

This system provides:

• Bidirectional Communication: Main ↔ Renderer.
• Type-Safe Events: Uses TypeScript interfaces for event payloads.
• Context Awareness: Events include sender context for window-specific logic.

The sequence diagram below shows how a renderer event is handled.

Controller and Service Architecture

The business logic and event handling are structured into Controllers and Services.

Controller Pattern

Controllers are responsible for handling IPC events. They are decorated with event listeners and contain lifecycle hooks for initialization.

• IPC Event Handling: Methods decorated with @ipcClientEvent process incoming events from the renderer.
• Lifecycle Hooks: beforeAppReady and afterAppReady hooks allow for logic to be executed at specific points in the application startup sequence.
• Type-Safe Communication: All IPC events and responses are strongly typed.

Sources: apps/desktop/README.md

Service Pattern

Services encapsulate business logic, making them reusable across different controllers.

• Business Logic Encapsulation: Separates complex logic from event handling.
• Dependency Management: Managed by the IoC container.
• Cross-Controller Sharing: Services can be accessed by multiple controllers via the service locator pattern.

Sources: apps/desktop/README.md

Bundled Apps

LobeChat features "Bundled Apps," which are pre-configured AI assistant templates designed for specific use cases. These are defined in the database and can be shared via a clean URL.

• URL Structure: https://pho.chat/apps/bundled/[id]
• Configuration: Each app has a pre-set model, system role, and chat configuration.
• Seeding: Initial apps are populated into the database using a seed script.

The following apps are created by default:

• Artifact Creator: For creating interactive HTML/CSS/JS content.
• Code Reviewer: For getting detailed code reviews.
• Content Writer: A professional content writing assistant.

Sources: scripts/seedBundledApps/index.ts, scripts/seedBundledApps/README.md, src/app/apps/bundled/[id]/page.tsx

Bundled App Data Structure

A bundled app is defined by the NewBundledApp schema.

Field	Type	Description
id	string	Unique identifier for the app, used in the URL.
title	string	The display name of the app.
description	string	A short description of the app's purpose.
avatar	string	An emoji or image URL for the app's icon.
systemRole	string	The system prompt that defines the AI's behavior.
config	object	Contains model, provider, and parameters (temperature, top_p).
chatConfig	object	Configuration for the chat interface, like displayMode.
openingMessage	string	The initial message displayed when a user starts a chat.
openingQuestions	string[]	A list of suggested questions to help the user get started.
isPublic	boolean	Determines if the app is publicly accessible.

Sources: scripts/seedBundledApps/index.ts

Local System and Artifact Tools

The application can be extended with tools that interact with the user's local file system or create artifacts like code blocks and diagrams.

Local System Tool

This tool allows the AI to interact with the local file system. Its capabilities are defined by a system prompt.

• Capabilities: listLocalFiles, readLocalFile, writeFile, searchLocalFiles, renameLocalFile, moveLocalFiles.
• Context: The tool is aware of common user directories like Desktop, Documents, and Downloads.
• Security: It requires user confirmation for write operations and handles file paths carefully.

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

Artifact Creator Tool

This tool allows the assistant to generate self-contained content blocks, such as code, documents, or diagrams, which are displayed in a separate UI window.

• Artifact Types:
  • application/lobe.artifacts.code (Code snippets)
  • text/markdown (Documents)
  • text/html (Renderable HTML)
  • image/svg+xml (Renderable SVG)
  • application/lobe.artifacts.mermaid (Mermaid diagrams)
  • application/lobe.artifacts.react (React components)
• Usage: The AI wraps the content in <lobeArtifact> tags with attributes for identifier, type, and title.

Sources: src/tools/artifacts/systemRole.ts