LibreChat
Development

Project Architecture

Overview of LibreChat's monorepo workspace structure and package boundaries.

Monorepo Structure

LibreChat is organized as a monorepo with clearly defined workspace boundaries:

WorkspaceLanguageSideDependencyPurpose
/apiJS (legacy)Backendpackages/api, packages/data-schemas, packages/data-provider, @librechat/agentsExpress server — minimize changes here
/packages/apiTypeScriptBackendpackages/data-schemas, packages/data-providerNew backend code lives here (TS only, consumed by /api)
/packages/data-schemasTypeScriptBackendpackages/data-providerDatabase models/schemas
/packages/data-providerTypeScriptShared—Shared API types, endpoints, data-service — used by both frontend and backend
/clientTypeScript/ReactFrontendpackages/data-provider, packages/clientFrontend SPA
/packages/clientTypeScriptFrontendpackages/data-providerShared frontend utilities

Key Principles

  • All new backend code must be TypeScript in /packages/api.
  • Keep /api changes to the absolute minimum — thin JS wrappers calling into /packages/api.
  • Database-specific shared logic belongs in /packages/data-schemas.
  • Frontend/backend shared API logic (endpoints, types, data-service) belongs in /packages/data-provider.

Build and Install

CommandPurpose
npm run smart-reinstallInstall deps (if lockfile changed) + build via Turborepo
npm run reinstallClean install — wipe node_modules and reinstall from scratch
npm run buildBuild all compiled code via Turborepo (parallel, cached)
npm run frontendBuild all compiled code sequentially (legacy fallback)
npm run build:data-providerRebuild packages/data-provider after changes
npm run backendStart the backend server
npm run backend:devStart backend with file watching (development)
npm run frontend:devStart frontend dev server with HMR (port 3090, requires backend running)
  • Node.js: v20.19.0+ or ^22.12.0 or >= 23.0.0
  • Database: MongoDB
  • Backend runs on http://localhost:3080/; frontend dev server on http://localhost:3090/

Note

For the full set of coding standards and conventions, see Code Standards and Conventions.

How is this guide?

Edit on GitHub

Previous

Debugging

Next

Code Standards and Conventions

On this page