Directory Structure

LobeHub uses a Monorepo architecture (@lobechat/ namespace). The top-level directory structure is as follows:

bash

lobehub/
├── apps/
│   └── desktop/               # Electron desktop app
├── packages/                  # Shared packages (@lobechat/*)
│   ├── agent-runtime/         # Agent runtime
│   ├── database/              # Database schemas, models, repositories
│   ├── model-runtime/         # Model runtime (AI provider adapters)
│   ├── builtin-tool-*/        # Built-in tool packages
│   ├── business/              # Cloud business slot packages
│   ├── context-engine/        # Context engine
│   ├── conversation-flow/     # Conversation flow
│   ├── editor-runtime/        # Editor runtime
│   ├── file-loaders/          # File loaders
│   ├── prompts/               # Prompt templates
│   └── ...                    # More shared packages
├── src/                       # Main app source code (see below)
├── locales/                   # i18n translation files (zh-CN, en-US, etc.)
├── e2e/                       # E2E tests (Cucumber + Playwright)
└── docs/                      # Documentation

src Directory

bash

src/
├── app/               # Next.js App Router (route groups and API routes)
├── business/          # Cloud-only business logic (client/server)
├── components/        # Reusable UI components
├── config/            # App configuration (client and server env vars)
├── const/             # Application constants and enums
├── envs/              # Environment variable definitions and validation
├── features/          # Business feature modules (Agent settings, plugin dev, etc.)
├── helpers/           # Utility helper functions
├── hooks/             # Reusable custom Hooks
├── layout/            # Global layout components (AuthProvider, GlobalProvider)
├── libs/              # Third-party integrations (better-auth, OIDC, tRPC, MCP, etc.)
├── locales/           # i18n default language files (English)
├── server/            # Server-side modules
│   ├── featureFlags/  # Feature flags
│   ├── globalConfig/  # Global configuration
│   ├── modules/       # Server modules (no DB access)
│   ├── routers/       # tRPC routers (async, lambda, mobile, tools)
│   └── services/      # Server services (with DB access)
├── services/          # Client-side service interfaces
├── store/             # Zustand state management
├── styles/            # Global styles and CSS-in-JS configurations
├── tools/             # Built-in tools (artifacts, inspectors, etc.)
├── types/             # TypeScript type definitions
├── utils/             # General utility functions
├── auth.ts            # Authentication configuration (Better Auth)
├── instrumentation.ts # App monitoring and telemetry setup
└── proxy.ts           # Next.js middleware proxy configuration

app Directory

The app directory follows Next.js App Router conventions, using Route Groups to organize backend services, platform variants, and application routes:

bash

app/
├── (backend)/                 # Backend API routes and services
│   ├── api/                   # REST API endpoints (auth, webhooks)
│   ├── f/                     # File service
│   ├── market/                # Market service
│   ├── middleware/            # Request middleware
│   ├── oidc/                  # OpenID Connect routes
│   ├── trpc/                  # tRPC API endpoints
│   │   ├── async/             # Async tRPC routes
│   │   ├── desktop/           # Desktop tRPC routes
│   │   ├── lambda/            # Lambda tRPC routes
│   │   └── tools/             # Tools tRPC routes
│   └── webapi/                # Web API endpoints (chat, models, tts, etc.)
├── [variants]/                # Platform and device variants
│   ├── (auth)/                # Auth pages (login, signup)
│   ├── (desktop)/             # Desktop-specific routes
│   ├── (main)/                # Main application routes (SPA)
│   │   ├── _layout/           # Layout components
│   │   ├── agent/             # Agent pages
│   │   ├── home/              # Home page
│   │   ├── image/             # Image generation
│   │   ├── memory/            # Memory management
│   │   ├── resource/          # Resource management
│   │   └── settings/          # Application settings
│   ├── (mobile)/              # Mobile-specific routes
│   ├── onboarding/            # Onboarding flow
│   ├── router/                # SPA router configuration
│   └── share/                 # Share pages
├── manifest.ts                # PWA manifest
├── robots.tsx                 # Robots.txt generation
├── sitemap.tsx                # Sitemap generation
└── sw.ts                      # Service Worker

Architecture Explanation

Route Groups:

(backend) — All server-side API routes, middleware, and backend services
[variants] — Dynamic route group for platform variants
(main) — Main SPA using React Router DOM

Platform Organization:

Supports multiple platforms (web, desktop, mobile) through route organization
Desktop-specific routes under (desktop)/
Mobile-specific routes under (mobile)/
Shared layout components in _layout/ directories

API Architecture:

REST APIs: (backend)/api/ and (backend)/webapi/
tRPC endpoints (src/server/routers/): grouped by runtime
- lambda/ — Main business routers (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, klavis)
- mobile/ — Mobile-specific routers

Data Flow:

Using a typical user action (e.g., updating Agent config) as an example, here's how data flows through each layer:

plaintext

React UI (src/features/, src/app/)
  │  User interaction triggers event
  ▼
Store Actions (src/store/)
  │  Zustand action updates local state, calls service
  ▼
Client Service (src/services/)
  │  Wraps tRPC client call, prepares request params
  ▼
tRPC Router (src/server/routers/lambda/)
  │  Validates input (zod), routes to service
  ▼
Server Service (src/server/services/)
  │  Executes business logic, calls DB model
  ▼
DB Model (packages/database/src/models/)
  │  Wraps Drizzle ORM queries
  ▼
PostgreSQL

For data reads, the flow is reversed: UI consumes data via store selectors, and stores fetch from the backend via SWR + tRPC queries.

Routing Architecture

The project uses hybrid routing: Next.js App Router handles static pages (e.g., auth pages), while React Router DOM powers the main SPA.

Entry: src/app/[variants]/page.tsx dispatches to desktop or mobile router based on device type.

Key configuration files:

Desktop router: src/app/[variants]/router/desktopRouter.config.tsx
Mobile router: src/app/[variants]/(mobile)/router/mobileRouter.config.tsx
Router utilities: src/utils/router.tsx

Desktop SPA Routes (React Router DOM):

bash

/                          # Home
/agent/:aid                # Agent conversation
/agent/:aid/profile        # Agent profile
/agent/:aid/cron/:cronId   # Cron task detail
/group/:gid                # Group conversation
/group/:gid/profile        # Group profile
/community                 # Community discovery (agent, model, provider, mcp)
/community/agent/:slug     # Agent detail page
/community/model/:slug     # Model detail page
/community/provider/:slug  # Provider detail page
/community/mcp/:slug       # MCP detail page
/resource                  # Resource management
/resource/library/:id      # Knowledge base detail
/settings/:tab             # Settings (profile, provider, etc.)
/settings/provider/:id     # Model provider configuration
/memory                    # Memory management
/image                     # Image generation
/page/:id                  # Page detail
/share/t/:id               # Share topic
/onboarding                # Onboarding flow

Mobile SPA Routes (React Router DOM):

bash

/                          # Home
/agent/:aid                # Agent conversation
/community                 # Community discovery
/settings                  # Settings home
/settings/:tab             # Settings detail
/settings/provider/:id     # Model provider configuration
/me                        # Personal center
/me/profile                # Profile
/me/settings               # Personal settings
/share/t/:id               # Share topic
/onboarding                # Onboarding flow