# Project Architecture (/docs/development/architecture)

## Monorepo Structure

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

| Workspace | Language | Side | Dependency | Purpose |
|---|---|---|---|---|
| `/api` | JS (legacy) | Backend | `packages/api`, `packages/data-schemas`, `packages/data-provider`, `@librechat/agents` | Express server — minimize changes here |
| `/packages/api` | **TypeScript** | Backend | `packages/data-schemas`, `packages/data-provider` | New backend code lives here (TS only, consumed by `/api`) |
| `/packages/data-schemas` | TypeScript | Backend | `packages/data-provider` | Database models/schemas |
| `/packages/data-provider` | TypeScript | Shared | — | Shared API types, endpoints, data-service — used by both frontend and backend |
| `/client` | TypeScript/React | Frontend | `packages/data-provider`, `packages/client` | Frontend SPA |
| `/packages/client` | TypeScript | Frontend | `packages/data-provider` | Shared 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

| Command | Purpose |
|---|---|
| `npm run smart-reinstall` | Install deps (if lockfile changed) + build via Turborepo |
| `npm run reinstall` | Clean install — wipe `node_modules` and reinstall from scratch |
| `npm run build` | Build all compiled code via Turborepo (parallel, cached) |
| `npm run frontend` | Build all compiled code sequentially (legacy fallback) |
| `npm run build:data-provider` | Rebuild `packages/data-provider` after changes |
| `npm run backend` | Start the backend server |
| `npm run backend:dev` | Start backend with file watching (development) |
| `npm run frontend:dev` | Start 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/`

<Callout type="info" title="Note">
  For the full set of coding standards and conventions, see [Code Standards and Conventions](/docs/development/conventions).
</Callout>