project-overview
This Claude Code skill provides a structured reference map of the LobeHub monorepo architecture, including directory layouts, technology stack, and key locations across apps, packages, and source code. Use it when onboarding to the repository, locating specific code layers, understanding the project structure, or navigating business logic implementations across the web platform, Electron desktop app, and backend services.
git clone --depth 1 https://github.com/lobehub/lobehub /tmp/project-overview && cp -r /tmp/project-overview/.agents/skills/project-overview ~/.claude/skills/project-overviewSKILL.md
# 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 LAdd documentation for a new AI provider — usage docs, env vars, Docker config, image resources.
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, 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.
Agent tracing CLI for execution snapshots. Use for agent-tracing, traces, snapshots, LLM call inspection, context engine data, agent step analysis, execution debugging, or pulling remote/production traces ("拉线上 tracing") by operation id. Also the first stop for debugging agent tool calls — wrong or missing tool_calls, unexpected tool arguments or results, which tools were available at a step, or why a tool ran where it did.
Build LobeHub builtin tool packages. Use when adding agent-callable tools, manifests, executors, runtimes, inspectors, renders, placeholders, streaming, interventions, portals, or tool registries.
Build multi-platform chat bots with the chat SDK. Use for Slack, Teams, Google Chat, Discord, GitHub, Linear bots, webhooks, mentions, slash commands, cards, modals, or streaming responses.
>