LobeHub Project Overview
The directory listings below are a curated map of key locations, not an
exhaustive tree. packages/, src/store/, route groups etc. grow over time —
run ls against the real directory for the current set.
Project Description
Open-source, modern-design AI Agent Workspace: LobeHub (previously LobeChat).
This repo is the open-source root (github.com/lobehub/lobehub, package @lobehub/lobehub).
Supported platforms:
- Web desktop/mobile
- Desktop (Electron) —
apps/desktop
- Mobile app (React Native) — separate repo, already launched (not in this monorepo)
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 |
Exact versions live in the root package.json — check there, not here.
Monorepo Layout
Flat layout — apps/, packages/, and src/ all sit at the repo root. No
git submodules.
(repo root)
├── apps/
│ ├── cli/ # LobeHub CLI
│ ├── desktop/ # Electron desktop app
│ └── server/ # Next.js-backed server (`@/server/*` alias)
│ └── src/
│ ├── router-hono/ # Hono endpoint routers and standalone runtime
│ └── ... # featureFlags, globalConfig, modules, routers, services, utils, workflows
├── docs/ # changelog, development, self-hosting, usage
├── locales/ # en-US, zh-CN, ...
├── packages/ # ~80 @lobechat/* workspace packages — `ls` for the full set. Key ones:
│ ├── agent-runtime/ # Agent runtime core
│ ├── agent-signal/ # Agent Signal pipeline
│ ├── agent-tracing/ # Tracing / snapshots
│ ├── builtin-tool-*/ # Per-tool packages (calculator, web-browsing, claude-code, ...)
│ ├── builtin-tools/ # Central registries that compose builtin-tool-*
│ ├── context-engine/
│ ├── database/ # src/{models,schemas,repositories}
│ ├── model-bank/ # Model definitions & provider cards
│ ├── model-runtime/ # src/{core,providers}
│ ├── locales/ # i18n source of truth: packages/locales/src/default/
│ ├── env/ # env schemas (@/envs/* → packages/env/src/*)
│ ├── app-config/
│ ├── business/ # Open-source stubs (config, const, model-bank, model-runtime) — overridden by cloud
│ ├── types/
│ └── utils/
└── src/
├── app/
│ ├── (backend)/ # api, f, market, middleware, oidc, trpc, webapi
│ ├── spa/ # SPA HTML template service
│ └── spa-auth/ # Auth HTML shell (SSR)
├── routes/ # SPA page segments (thin — delegate to features/)
│ └── (main)/ (mobile)/ (desktop)/ (popup)/ auth/ onboarding/ share/
├── spa/ # SPA entries + router config
│ ├── entry.{web,mobile,desktop,popup}.tsx
│ └── router/
├── business/ # Open-source stubs (client/server) — cloud repo provides real impls
├── features/ # Domain business components
├── store/ # ~30 zustand stores — `ls` for the full set
└── ... # components, hooks, layout, libs, services, types, utils
Architecture Map
| Layer |
Location |
| UI Components |
src/components, src/features |
| SPA Pages |
src/routes/ |
| React Router |
src/spa/router/ |
| Global Providers |
src/layout |
| Zustand Stores |
src/store |
| Client Services |
src/services/ |
| REST API |
src/app/(backend)/webapi |
| tRPC Routers |
apps/server/src/routers/{async|lambda|mobile|tools} |
| Server Services |
apps/server/src/services (can access DB) |
| Server Modules |
apps/server/src/modules (no DB access) |
| Feature Flags |
apps/server/src/featureFlags |
| Global Config |
apps/server/src/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 |
packages/builtin-tool-*, packages/builtin-tools |
| Open-source stub |
src/business/*, packages/business/* (this repo) |
Data Flow
React UI → Store Actions → Client Service → TRPC Lambda → Server Services → DB Model → PostgreSQL
Note: Relationship to the Cloud Repo
This open-source repo is consumed by a separate, private cloud (SaaS) repo
as a git submodule mounted at lobehub/. The cloud repo provides:
src/business/{client,server} and packages/business/* implementations
that override the stubs shipped here.
- Cloud-only routes (e.g.
(cloud)/, embed/), cloud-only stores (e.g.
subscription/), cloud-only TRPC routers (billing, budget, risk control, …),
and Vercel cron routes under src/app/(backend)/cron/.
- File-resolution order in cloud:
@/store/x → cloud src/store/x first, then
lobehub/packages/store/src/x, then lobehub/src/store/x. Cloud override wins.
When working in this repo alone, ignore the cloud layer — the stubs in
src/business/ and packages/business/ are the source of truth here.
1---
2name: project-overview
3description: 'Use for the OSS repository map, code-layer lookup, apps/packages/src ownership and business stubs.'
4user-invocable: false
5metadata:
6 source: https://skillmd.com/skills/lobehub/project-overview
7---
8
9# LobeHub Project Overview
10
11> The directory listings below are a **curated map of key locations**, not an
12> exhaustive tree. `packages/`, `src/store/`, route groups etc. grow over time —
13> run `ls` against the real directory for the current set.
14
15## Project Description
16
17Open-source, modern-design AI Agent Workspace: **LobeHub** (previously LobeChat).
18This repo is the **open-source root** (`github.com/lobehub/lobehub`, package `@lobehub/lobehub`).
19
20**Supported platforms:**
21
22- Web desktop/mobile
23- Desktop (Electron) — `apps/desktop`
24- Mobile app (React Native) — **separate repo, already launched** (not in this monorepo)
25
26**Logo emoji:** 🤯
27
28## Complete Tech Stack
29
30| Category | Technology |
31| ------------- | ------------------------------------------ |
32| Framework | Next.js 16 + React 19 |
33| Routing | SPA inside Next.js with `react-router-dom` |
34| Language | TypeScript |
35| UI Components | `@lobehub/ui`, antd |
36| CSS-in-JS | antd-style |
37| Icons | lucide-react, `@ant-design/icons` |
38| i18n | react-i18next |
39| State | zustand |
40| URL Params | nuqs |
41| Data Fetching | SWR |
42| React Hooks | aHooks |
43| Date/Time | dayjs |
44| Utilities | es-toolkit |
45| API | TRPC (type-safe) |
46| Database | Neon PostgreSQL + Drizzle ORM |
47| Testing | Vitest |
48
49> Exact versions live in the root `package.json` — check there, not here.
50
51## Monorepo Layout
52
53Flat layout — `apps/`, `packages/`, and `src/` all sit at the repo root. No
54git submodules.
55
56```
57(repo root)
58├── apps/
59│ ├── cli/ # LobeHub CLI
60│ ├── desktop/ # Electron desktop app
61│ └── server/ # Next.js-backed server (`@/server/*` alias)
62│ └── src/
63│ ├── router-hono/ # Hono endpoint routers and standalone runtime
64│ └── ... # featureFlags, globalConfig, modules, routers, services, utils, workflows
65├── docs/ # changelog, development, self-hosting, usage
66├── locales/ # en-US, zh-CN, ...
67├── packages/ # ~80 @lobechat/* workspace packages — `ls` for the full set. Key ones:
68│ ├── agent-runtime/ # Agent runtime core
69│ ├── agent-signal/ # Agent Signal pipeline
70│ ├── agent-tracing/ # Tracing / snapshots
71│ ├── builtin-tool-*/ # Per-tool packages (calculator, web-browsing, claude-code, ...)
72│ ├── builtin-tools/ # Central registries that compose builtin-tool-*
73│ ├── context-engine/
74│ ├── database/ # src/{models,schemas,repositories}
75│ ├── model-bank/ # Model definitions & provider cards
76│ ├── model-runtime/ # src/{core,providers}
77│ ├── locales/ # i18n source of truth: packages/locales/src/default/
78│ ├── env/ # env schemas (@/envs/* → packages/env/src/*)
79│ ├── app-config/
80│ ├── business/ # Open-source stubs (config, const, model-bank, model-runtime) — overridden by cloud
81│ ├── types/
82│ └── utils/
83└── src/
84 ├── app/
85 │ ├── (backend)/ # api, f, market, middleware, oidc, trpc, webapi
86 │ ├── spa/ # SPA HTML template service
87 │ └── spa-auth/ # Auth HTML shell (SSR)
88 ├── routes/ # SPA page segments (thin — delegate to features/)
89 │ └── (main)/ (mobile)/ (desktop)/ (popup)/ auth/ onboarding/ share/
90 ├── spa/ # SPA entries + router config
91 │ ├── entry.{web,mobile,desktop,popup}.tsx
92 │ └── router/
93 ├── business/ # Open-source stubs (client/server) — cloud repo provides real impls
94 ├── features/ # Domain business components
95 ├── store/ # ~30 zustand stores — `ls` for the full set
96 └── ... # components, hooks, layout, libs, services, types, utils
97```
98
99## Architecture Map
100
101| Layer | Location |
102| ---------------- | -------------------------------------------------------- |
103| UI Components | `src/components`, `src/features` |
104| SPA Pages | `src/routes/` |
105| React Router | `src/spa/router/` |
106| Global Providers | `src/layout` |
107| Zustand Stores | `src/store` |
108| Client Services | `src/services/` |
109| REST API | `src/app/(backend)/webapi` |
110| tRPC Routers | `apps/server/src/routers/{async\|lambda\|mobile\|tools}` |
111| Server Services | `apps/server/src/services` (can access DB) |
112| Server Modules | `apps/server/src/modules` (no DB access) |
113| Feature Flags | `apps/server/src/featureFlags` |
114| Global Config | `apps/server/src/globalConfig` |
115| DB Schema | `packages/database/src/schemas` |
116| DB Model | `packages/database/src/models` |
117| DB Repository | `packages/database/src/repositories` |
118| Third-party | `src/libs` (analytics, oidc, etc.) |
119| Builtin Tools | `packages/builtin-tool-*`, `packages/builtin-tools` |
120| Open-source stub | `src/business/*`, `packages/business/*` (this repo) |
121
122## Data Flow
123
124```
125React UI → Store Actions → Client Service → TRPC Lambda → Server Services → DB Model → PostgreSQL
126```
127
128## Note: Relationship to the Cloud Repo
129
130This open-source repo is consumed by a **separate, private cloud (SaaS) repo**
131as a git submodule mounted at `lobehub/`. The cloud repo provides:
132
133- **`src/business/{client,server}`** and **`packages/business/*`** implementations
134 that override the stubs shipped here.
135- Cloud-only routes (e.g. `(cloud)/`, `embed/`), cloud-only stores (e.g.
136 `subscription/`), cloud-only TRPC routers (billing, budget, risk control, …),
137 and Vercel cron routes under `src/app/(backend)/cron/`.
138- File-resolution order in cloud: `@/store/x` → cloud `src/store/x` first, then
139 `lobehub/packages/store/src/x`, then `lobehub/src/store/x`. **Cloud override wins.**
140
141When working in this repo alone, ignore the cloud layer — the stubs in
142`src/business/` and `packages/business/` are the source of truth here.