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.