Directory Structure
LobeHub uses a Monorepo architecture (@lobechat/ namespace).
The top-level directory structure is as follows:
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.
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) andspa-auth/[locale]/[[...path]]/route.ts(auth pages).src/routes/— SPA page segments, grouped by platform route group ((main),(mobile),(desktop),(popup)), plusauth/,onboarding/, andshare/. These are thin files that delegate tosrc/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 underrouter/.
Architecture Explanation
Route Groups:
(backend)— All server-side API routes, middleware, and backend services(main)/(mobile)/(desktop)/(popup)— Platform-specific SPA route groups undersrc/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 runtimelambda/— 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:
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 withdesktopRouter.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):
Mobile SPA Routes (React Router DOM):