mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-27 13:29:15 +07:00
225 lines
9.2 KiB
Plaintext
225 lines
9.2 KiB
Plaintext
---
|
|
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
|
|
```
|