lobehub/docs/development/basic/folder-structure.mdx

---
title: Directory Structure
description: >-
  Explore the organized directory structure of LobeHub, including app,
  components, and services.
tags:
  - LobeHub
  - Directory Structure
  - Next.js
  - App Router
  - API Architecture
---

# 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](https://nextjs.org/docs/app/building-your-application/routing/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
```