project-overview

An architecture map and onboarding reference for the LobeHub open-source monorepo (formerly LobeChat), a modern AI Agent Workspace hosted at github.com/lobehub/lobehub. It orients contributors to a flat monorepo layout where apps/, packages/, and src/ all sit at the repo root with no git submodules, and provides a curated (not exhaustive) map of key locations — the reader is reminded to ls the real directories since packages, stores, and route groups grow over time. The document summarizes the full tech stack: Next.js 16 with React 19, TypeScript, SPA routing via react-router-dom, @lobehub/ui and antd components with antd-style CSS-in-JS, zustand state, nuqs URL params, SWR data fetching, ahooks, dayjs, es-toolkit, type-safe tRPC, a Neon PostgreSQL database with Drizzle ORM, and Vitest testing, noting that exact versions live in the root package.json. Under apps/ it describes the cli, desktop (Electron), device-gateway, and server (the Next.js-backed backend with featureFlags, globalConfig, modules, routers, services, utils, and workflows); packages/ holds roughly 80 @lobechat/* workspace packages including agent-runtime, model-runtime, model-bank, database, and builtin-tool packages; and src/ contains the app, routes, spa entries, features, store, and business layers. An architecture table maps each layer (UI components, SPA pages, React Router, providers, stores, client services, REST and tRPC APIs, server services and modules, DB schema/model/repository, third-party libs, builtin tools, and open-source stubs) to its location, and a data-flow diagram traces React UI through store actions, client services, tRPC lambda, server services, DB models, to PostgreSQL. A final section explains the relationship to a separate private cloud SaaS repo that mounts this repo as a submodule and overrides the business stubs, clarifying that within this repo the stubs are the source of truth.