mirror of
https://github.com/lobehub/lobehub.git
synced 2026-03-26 13:19:34 +07:00
463d6c8762
* 🔧 chore(vscode): add typescript.tsdk and disable mdx server Fix MDX extension crash caused by Cursor's bundled TypeScript version * 🔧 chore(claude): add skills symlink to .claude directory * 📝 docs: update development guides with current tech stack and architecture - Update tech stack: Next.js 16 + React 19, hybrid routing (App Router + React Router DOM), tRPC, Drizzle ORM + PostgreSQL, react-i18next - Update directory structure to reflect monorepo layout (apps/, packages/, e2e/, locales/) - Expand src/server/ with detailed subdirectory descriptions - Add complete SPA routing architecture with desktop and mobile route tables - Add tRPC router grouping details (lambda, async, tools, mobile) - Add data flow diagram - Simplify dev setup section to link to setup-development guide - Fix i18n default language description (English, not Chinese) - Sync all changes between zh-CN and English versions * 📝 docs: expand data flow diagram in folder structure guide Replace the single-line data flow with a detailed layer-by-layer flow diagram showing each layer's location and responsibility. * 📝 docs: modernize feature development guide - Remove outdated clientDB/pglite/indexDB references - Update schema path to packages/database/src/schemas/ - Update types path to packages/types/src/ - Replace inline migration steps with link to db-migrations guide - Add complete layered architecture table (Client Service, WebAPI, tRPC Router, Server Service, Server Module, Repository, DB Model) - Clarify Client Service as frontend code - Add i18n handling section with workflow and key naming convention - Remove verbose CSS style code, keep core business logic only - Expand testing section with commands, skill refs, and CI tip * 🔥 docs: remove outdated frontend feature development guide Content is superseded by the comprehensive feature-development guide which covers the full chain from schema to testing. * 📝 docs: add LobeHub ecosystem and community resources Add official ecosystem packages (LobeUI, LobeIcons, LobeCharts, LobeEditor, LobeTTS, LobeLint, Lobe i18n, MCP Mark) and community platforms (Agent Market, MCP Market, YouTube, X, Discord). * 📝 docs: improve contributing guidelines and resources - Clarify semantic release triggers (feat/fix vs style/chore) - Add testing section with Vitest/E2E/CI requirements - Update contribution steps to include CI check - Add LobeHub ecosystem packages and community platforms to resources * 📝 docs: rewrite architecture guide to reflect current platform design * 📝 docs: add code quality tools to architecture guide * 📝 docs: rewrite chat-api guide to reflect current architecture - Update sequence diagram with Agent Runtime loop as core execution engine - Replace PluginGateway with ToolExecution layer (Builtin/MCP/Plugin) - Update all path references (model-runtime, agent-runtime, fetch-sse packages) - Split old AgentRuntime section into Model Runtime + Agent Runtime - Add tool calling taxonomy: Builtin, MCP, and Plugin (deprecated) - Add client-side vs server-side execution section - Remove outdated adapter pseudo-code examples * 📝 docs: update file paths in add-new-image-model guide - src/libs/standard-parameters/ → packages/model-bank/src/standard-parameters/ - src/config/aiModels/ → packages/model-bank/src/aiModels/ - src/libs/model-runtime/ → packages/model-runtime/src/providers/ * 📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides The S3_PUBLIC_DOMAIN env var was incorrectly removed from all documentation in commit4a87b31. This variable is still required by the code (src/server/services/file/impls/s3.ts) to generate public URLs for uploaded files. Without it, image URLs sent to vision models are just S3 keys instead of full URLs. Closes #12161 * 📦 chore: pin @lobehub/ui to 4.33.4 to fix SortableList type errors @lobehub/ui 4.34.0 introduced breaking type changes in SortableList where SortableListItem became strict, causing type incompatibility in onChange and renderItem callbacks across 6 files. Pin to 4.33.4 via pnpm overrides to enforce consistent version across monorepo. * 🐛 fix: correct ReadableStream type annotations and add dom.asynciterable - Add dom.asynciterable to tsconfig lib for ReadableStream async iteration - Fix createCallbacksTransformer return type: TransformStream<string, Uint8Array> - Update stream function return types from ReadableStream<string> to ReadableStream<Uint8Array> (llama.ts, ollama.ts, claude.ts) - Remove @ts-ignore from for-await loops in test files - Add explicit string[] type for chunks arrays * Revert "📝 docs: restore S3_PUBLIC_DOMAIN in deployment guides" This reverts commit24073f83d3.
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
|
|
lobe-chat/
|
|
├── 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
|
|
```
|