home / skills / lobehub / lobe-chat / project-overview
This skill helps you explore a TypeScript monorepo by summarizing project structure, architecture, and key components for quick onboarding.
npx playbooks add skill lobehub/lobe-chat --skill project-overviewReview the files below or copy the command above to add this skill to your agents.
---
name: project-overview
description: Complete project architecture and structure guide. Use when exploring the codebase, understanding project organization, finding files, or needing comprehensive architectural context. Triggers on architecture questions, directory navigation, or project overview needs.
---
# LobeChat Project Overview
## Project Description
Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat).
**Supported platforms:**
- Web desktop/mobile
- Desktop (Electron)
- Mobile app (React Native) - coming soon
**Logo emoji:** š¤Æ
## Complete Tech Stack
| Category | Technology |
|----------|------------|
| Framework | Next.js 16 + React 19 |
| Routing | SPA inside Next.js with `react-router-dom` |
| Language | TypeScript |
| UI Components | `@lobehub/ui`, antd |
| CSS-in-JS | antd-style |
| Icons | lucide-react, `@ant-design/icons` |
| i18n | react-i18next |
| State | zustand |
| URL Params | nuqs |
| Data Fetching | SWR |
| React Hooks | aHooks |
| Date/Time | dayjs |
| Utilities | es-toolkit |
| API | TRPC (type-safe) |
| Database | Neon PostgreSQL + Drizzle ORM |
| Testing | Vitest |
## Complete Project Structure
Monorepo using `@lobechat/` namespace for workspace packages.
```
lobe-chat/
āāā apps/
ā āāā desktop/ # Electron desktop app
āāā docs/
ā āāā changelog/
ā āāā development/
ā āāā self-hosting/
ā āāā usage/
āāā locales/
ā āāā en-US/
ā āāā zh-CN/
āāā packages/
ā āāā agent-runtime/ # Agent runtime
ā āāā builtin-agents/
ā āāā builtin-tool-*/ # Builtin tool packages
ā āāā business/ # Cloud-only business logic
ā ā āāā config/
ā ā āāā const/
ā ā āāā model-runtime/
ā āāā config/
ā āāā const/
ā āāā context-engine/
ā āāā conversation-flow/
ā āāā database/
ā ā āāā src/
ā ā āāā models/
ā ā āāā schemas/
ā ā āāā repositories/
ā āāā desktop-bridge/
ā āāā edge-config/
ā āāā editor-runtime/
ā āāā electron-client-ipc/
ā āāā electron-server-ipc/
ā āāā fetch-sse/
ā āāā file-loaders/
ā āāā memory-user-memory/
ā āāā model-bank/
ā āāā model-runtime/
ā ā āāā src/
ā ā āāā core/
ā ā āāā providers/
ā āāā observability-otel/
ā āāā prompts/
ā āāā python-interpreter/
ā āāā ssrf-safe-fetch/
ā āāā types/
ā āāā utils/
ā āāā web-crawler/
āāā src/
ā āāā app/
ā ā āāā (backend)/
ā ā ā āāā api/
ā ā ā āāā f/
ā ā ā āāā market/
ā ā ā āāā middleware/
ā ā ā āāā oidc/
ā ā ā āāā trpc/
ā ā ā āāā webapi/
ā ā āāā [variants]/
ā ā ā āāā (auth)/
ā ā ā āāā (main)/
ā ā ā āāā (mobile)/
ā ā ā āāā onboarding/
ā ā ā āāā router/
ā ā āāā desktop/
ā āāā business/ # Cloud-only (client/server)
ā ā āāā client/
ā ā āāā locales/
ā ā āāā server/
ā āāā components/
ā āāā config/
ā āāā const/
ā āāā envs/
ā āāā features/
ā āāā helpers/
ā āāā hooks/
ā āāā layout/
ā ā āāā AuthProvider/
ā ā āāā GlobalProvider/
ā āāā libs/
ā ā āāā better-auth/
ā ā āāā oidc-provider/
ā ā āāā trpc/
ā āāā locales/
ā ā āāā default/
ā āāā server/
ā ā āāā featureFlags/
ā ā āāā globalConfig/
ā ā āāā modules/
ā ā āāā routers/
ā ā ā āāā async/
ā ā ā āāā lambda/
ā ā ā āāā mobile/
ā ā ā āāā tools/
ā ā āāā services/
ā āāā services/
ā āāā store/
ā ā āāā agent/
ā ā āāā chat/
ā ā āāā user/
ā āāā styles/
ā āāā tools/
ā āāā types/
ā āāā utils/
āāā e2e/ # E2E tests (Cucumber + Playwright)
```
## Architecture Map
| Layer | Location |
|-------|----------|
| UI Components | `src/components`, `src/features` |
| Global Providers | `src/layout` |
| Zustand Stores | `src/store` |
| Client Services | `src/services/` |
| REST API | `src/app/(backend)/webapi` |
| tRPC Routers | `src/server/routers/{async\|lambda\|mobile\|tools}` |
| Server Services | `src/server/services` (can access DB) |
| Server Modules | `src/server/modules` (no DB access) |
| Feature Flags | `src/server/featureFlags` |
| Global Config | `src/server/globalConfig` |
| DB Schema | `packages/database/src/schemas` |
| DB Model | `packages/database/src/models` |
| DB Repository | `packages/database/src/repositories` |
| Third-party | `src/libs` (analytics, oidc, etc.) |
| Builtin Tools | `src/tools`, `packages/builtin-tool-*` |
| Cloud-only | `src/business/*`, `packages/business/*` |
## Data Flow
```
React UI ā Store Actions ā Client Service ā TRPC Lambda ā Server Services ā DB Model ā PostgreSQL
```
This skill provides a complete project architecture and structure guide for the LobeHub codebase. It helps you quickly understand repo layout, key packages, and where to find UI, server, and database code. Use it to orient new contributors, plan changes, or trace feature implementations across layers.
The skill inspects the monorepo layout and maps responsibilities to folders and packages. It highlights core technologies (Next.js, TypeScript, TRPC, Neon/Postgres, Drizzle) and shows data flow from React UI through zustand stores to TRPC lambdas and the database. It also points to location-specific artifacts like DB schemas, server routers, builtin tools, and cloud-only logic.
Where are frontend routes and variants defined?
Frontend variants and routing live in src/app/[variants] for auth, main, mobile and src/app/(backend)/webapi for backend endpoints.
Which packages are cloud-only?
Cloud-only logic is grouped under src/business and packages/business; avoid importing these into pure client builds.