project-overview ยท diff

git:20260818.ed2fb66 to git:20260907.25bf231

1 added, 1 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
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.'
+ description: 'Use for the OSS repository map, code-layer lookup, apps/packages/src ownership and business stubs.'
user-invocable: false
---
# 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.