project-overview

Complete project architecture guide for LobeHub, an open-source AI Agent Workspace built on Next.js and React. Monorepo structure with @lobechat/ namespace packages covering agent runtime, model providers, database, tools, and platform-specific bridges (Electron, web, mobile) Tech stack includes Next.js 16, React 19, TypeScript, Zustand for state, tRPC for type-safe APIs, Neon PostgreSQL with Drizzle ORM, and antd-style for CSS-in-JS Three deployment targets: web (desktop/mobile), Electron desktop app, and React Native mobile (coming soon) Data flow: React UI → Zustand stores → client services → tRPC routers → server services → Drizzle models → PostgreSQL; SPA routing via react-router-dom inside Next.js

INSTALLATION

npx skills add https://github.com/lobehub/lobehub --skill project-overview

Run in your project or agent environment. Adjust flags if your CLI version differs.

SKILL.md

LobeHub Project Overview

Name: project-overview
Author: lobehub

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).

Supported platforms:

Web desktop/mobile

Desktop (Electron)

Mobile app (React Native) — separate repo, already launched (not in this monorepo)

Logo emoji: 🤯

Complete Tech Stack

Monorepo Layout

This is a monorepo extending the open-source lobehub submodule. Two repos:

cloud repo root — src/ and packages/business/ (config, const, model-runtime) hold cloud-only SaaS code that overrides/extends the submodule. See AGENTS.md for the override mechanism.

**lobehub/ submodule** — the open-source product core.

lobehub/ submodule — key directories

lobehub/

├── apps/

│   ├── cli/                 # LobeHub CLI

│   ├── desktop/             # Electron desktop app

│   └── device-gateway/      # Device gateway service

├── 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

│   ├── agent-signal/         # Agent Signal pipeline

│   ├── builtin-tool-*/       # Builtin tool packages

│   ├── builtin-tools/        # Builtin tool registries

│   ├── context-engine/

│   ├── database/             # src/{models,schemas,repositories}

│   ├── model-bank/           # Model definitions &#x26; provider cards

│   ├── model-runtime/        # src/{core,providers}

│   ├── 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 (~50) overridden by cloud src/business/

    ├── features/             # Domain business components

    ├── store/                # ~28 zustand stores — `ls` for the full set

    ├── server/               # featureFlags, globalConfig, modules, routers, services

    └── ...                   # components, hooks, layout, libs, locales, services, types, utils

cloud repo — key directories

(cloud root)

├── packages/business/        # Cloud overrides: config, const, model-runtime

├── src/

│   ├── business/             # Cloud impls of submodule stubs (client/server/locales)

│   ├── routes/               # Cloud-only route groups: (cloud)/, embed/

│   ├── store/                # Cloud-only stores (e.g. subscription/)

│   ├── server/               # Cloud routers &#x26; services (billing, budget, risk control...)

│   └── app/(backend)/cron/   # Vercel cron routes (schedules declared in root vercel.ts)

└── vercel.ts                 # Cron schedule declarations

File search rule: a path like @/store/x resolves cloud src/store/x first, then

lobehub/packages/store/src/x, then lobehub/src/store/x. Cloud override wins.

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

src/server/routers/{async|lambda|mobile|tools}

Server Services

src/server/services (can access DB)

Server Modules

src/server/modules (no DB access)

Feature Flags

src/server/featureFlags

Global Config

src/server/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

src/tools, packages/builtin-tool-*

Cloud-only

src/business/*, packages/business/* (cloud repo)

Data Flow

React UI → Store Actions → Client Service → TRPC Lambda → Server Services → DB Model → PostgreSQL