--- 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 ```