Directory Structure

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

bash

lobehub/
├── apps/
│   ├── cli/                   # LobeHub CLI
│   ├── desktop/                # Electron desktop app
│   └── server/                 # Standalone server (tRPC routers, services, modules)
├── 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
│   ├── builtin-tools/         # Built-in tools registry (inspectors, interventions, renders, etc.)
│   ├── business/              # Cloud business slot packages
│   ├── context-engine/        # Context engine
│   ├── conversation-flow/     # Conversation flow
│   ├── editor-runtime/        # Editor runtime
│   ├── file-loaders/          # File loaders
│   ├── prompts/               # Prompt templates
│   ├── app-config/            # App configuration (client and server env vars)
│   ├── env/                   # Environment variable definitions and validation
│   ├── locales/               # i18n default language files (English) and resources
│   └── ...                    # 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

config/, envs/, locales/, and tools/ have moved out of src/ into standalone packages — packages/app-config, packages/env, packages/locales, and packages/builtin-tools. The @/config/*, @/envs/*, and @/locales/* path aliases resolve to those packages first (see tsconfig.json), so most imports don't need to change.

bash

src/
├── app/               # Next.js App Router: backend API routes + SPA/auth HTML shell serving
│   ├── (backend)/     # Backend API routes (auth, webhooks, trpc, webapi, oidc, oauth)
│   ├── spa/           # SPA HTML template route (serves the Vite-built SPA bundle)
│   └── spa-auth/      # Auth pages HTML template route
├── business/          # Cloud-only business logic (client/server)
├── components/        # Reusable UI components
├── const/             # Application constants and enums
├── 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.)
├── routes/            # SPA page segments (layout + page files), grouped by platform
│   ├── (main)/        # Desktop routes
│   ├── (mobile)/      # Mobile routes
│   ├── (desktop)/     # Desktop-only routes (e.g. desktop onboarding)
│   ├── (popup)/       # Popup window routes
│   ├── auth/          # Auth pages (signin, signup, oauth, ...)
│   ├── onboarding/    # Onboarding flow
│   └── share/         # Share pages
├── server/            # Remaining server-side modules not yet moved to apps/server
│                       # (SEO metadata, SPA HTML rendering, composio services, workflows-hono)
├── services/          # Client-side service interfaces
├── spa/               # SPA entry points and React Router config
│   ├── entry.web.tsx / entry.mobile.tsx / entry.desktop.tsx / entry.popup.tsx / entry.auth.tsx
│   └── router/        # Router configs (desktopRouter.config.tsx, mobileRouter.config.tsx,
│                       # popupRouter.config.tsx, authRouter.config.tsx)
├── store/             # Zustand state management
├── styles/            # Global styles and CSS-in-JS configurations
├── 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, routes, and spa Directories

Page routing is now split across three directories:

src/app/ — Next.js App Router. Only handles backend API routes ((backend)/) and the two Next.js routes that serve the SPA's HTML shell: spa/[variants]/[[...path]]/route.ts (main app) and spa-auth/[locale]/[[...path]]/route.ts (auth pages).
src/routes/ — SPA page segments, grouped by platform route group ((main), (mobile), (desktop), (popup)), plus auth/, onboarding/, and share/. These are thin files that delegate to src/features/* for actual UI and business logic.
src/spa/ — SPA entry points (entry.web.tsx, entry.mobile.tsx, entry.desktop.tsx, entry.popup.tsx, entry.auth.tsx) and React Router config under router/.

bash

app/
├── (backend)/                 # Backend API routes and services
│   ├── api/                   # REST API endpoints (auth, webhooks)
│   ├── f/                     # File service
│   ├── market/                # Market service
│   ├── middleware/            # Request middleware
│   ├── oauth/                 # OAuth routes
│   ├── 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.)
├── spa/[variants]/[[...path]]/route.ts       # Serves the main SPA HTML shell
├── spa-auth/[locale]/[[...path]]/route.ts    # Serves the auth pages HTML shell
├── [variants]/metadata.ts     # Shared SEO metadata for variant routes
├── manifest.ts                 # PWA manifest
├── robots.tsx                  # Robots.txt generation
└── sitemap.tsx                 # Sitemap generation

bash

src/routes/
├── (main)/            # Desktop routes: agent, group, home, resource, settings, memory, ...
├── (mobile)/          # Mobile routes: (home), chat, community, me, settings
├── (desktop)/         # Desktop-only routes (e.g. desktop-onboarding)
├── (popup)/           # Popup window routes: agent, group
├── auth/              # Auth pages: signin, signup, oauth, reset-password, verify-email, ...
├── onboarding/        # Onboarding flow
└── share/             # Share pages: t/[id], page/[id]

bash

src/spa/
├── entry.web.tsx           # Desktop web entry
├── entry.mobile.tsx        # Mobile entry
├── entry.desktop.tsx       # Electron desktop entry
├── entry.popup.tsx         # Popup window entry
├── entry.auth.tsx          # Auth pages entry
└── router/
    ├── desktopRouter.config.tsx           # Desktop React Router routes
    ├── desktopRouter.config.desktop.tsx   # Desktop (Electron) variant, kept in sync
    ├── mobileRouter.config.tsx            # Mobile React Router routes
    ├── popupRouter.config.tsx             # Popup window routes
    └── authRouter.config.tsx              # Auth pages routes

Architecture Explanation

Route Groups:

(backend) — All server-side API routes, middleware, and backend services
(main) / (mobile) / (desktop) / (popup) — Platform-specific SPA route groups under src/routes/

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 (apps/server/src/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, composio)
- 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/routes/)
  │  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 (apps/server/src/routers/lambda/)
  │  Validates input (zod), routes to service
  ▼
Server Service (apps/server/src/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 serves the SPA's HTML shell and static/auth pages, while React Router DOM powers the main SPA once the bundle loads in the browser.

Entry: The Next.js route src/app/spa/[variants]/[[...path]]/route.ts renders the HTML shell (desktop or mobile template based on device type), which then boots the matching Vite entry in src/spa/ (entry.web.tsx, entry.mobile.tsx, or entry.desktop.tsx) to mount the React Router app.

Key configuration files:

Desktop router: src/spa/router/desktopRouter.config.tsx (kept in sync with desktopRouter.config.desktop.tsx)
Mobile router: src/spa/router/mobileRouter.config.tsx
Popup router: src/spa/router/popupRouter.config.tsx
Auth router: src/spa/router/authRouter.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