菜单
LobeHub open-source monorepo architecture map. Use when locating code layers, understanding apps/packages/src layout, business stubs, project structure, or onboarding to the repository.
| name | project-overview |
| description | LobeHub open-source monorepo architecture map. Use when locating code layers, understanding apps/packages/src layout, business stubs, project structure, or onboarding to the repository. |
| user-invocable | false |
The directory listings below are a curated map of key locations, not an exhaustive tree.
packages/,src/store/, route groups etc. grow over time — runlsagainst the real directory for the current set.
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:
apps/desktopLogo emoji: 🤯
| 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.
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
│ ├── device-gateway/ # Device gateway service
│ └── server/ # Next.js-backed server: featureFlags, globalConfig, modules, routers, services, utils, workflows (`@/server/*` alias)
├── 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}
│ ├── 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
│ └── [variants]/(auth)/ # Auth pages (SSR required)
├── routes/ # SPA page segments (thin — delegate to features/)
│ └── (main)/ (mobile)/ (desktop)/ (popup)/ 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
├── server/ # standalone-Hono server pieces only: agent-hono, workflows-hono (main backend lives in `apps/server`)
└── ... # components, hooks, layout, libs, locales, services, types, utils
| 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) |
React UI → Store Actions → Client Service → TRPC Lambda → Server Services → DB Model → PostgreSQL
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)/, embed/), cloud-only stores (e.g.
subscription/), cloud-only TRPC routers (billing, budget, risk control, …),
and Vercel cron routes under src/app/(backend)/cron/.@/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.
LobeHub Drizzle ORM schema and query style. Use for pgTable schemas, indexes, joins, inferred types, db.select/db.query, schema fields, foreign keys, junction tables, or postgres query patterns.
LobeHub code review checklist. Use when reviewing a PR, diff, or branch for console leftovers, return await, secrets, i18n, desktop router drift, UI imports, migrations, or cloud impact.
Vitest testing guide. Use when writing or updating tests, fixing failing tests, improving coverage, debugging test issues, or setting up mocks.
Add server-side environment variables that control default values for user settings.
Agent runtime lifecycle hooks. Use for before/after tool or step hooks, tool mocks, human intervention, sub-agent calls, context compression, evals, tracing, callAgent, or lifecycle events.
Build or extend LobeHub Agent Signal pipelines. Use for signal sources, signal/action types, policies, middleware, workflow handoff, dedupe, scope behavior, or observability.