# librechat-ai/librechat architecture

> Architecture diagram of the GitHub repository librechat-ai/librechat, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/librechat-ai/librechat
- Repository: https://github.com/librechat-ai/librechat

## Overview

LibreChat is a self-hosted conversational AI application spanning a browser client and an API server. Users configure models or Agents, submit chat turns, and receive streamed responses with tools, attachments, and generated artifacts. The README also describes distinct workflows for authentication, web search, code execution, scheduling, and observability. The graph reflects documented capabilities and relationships visible in the supplied excerpts and source index; some subsystems are represented at directory level because their implementation files were not sampled.

Main entry points: [`api/server/controllers/agents`](https://github.com/librechat-ai/librechat/tree/main/api/server/controllers/agents) (Agents), [`client/src/App.jsx`](https://github.com/librechat-ai/librechat/blob/main/client/src/App.jsx) (Chat UI), [`api/server/services/Runs/StreamRunManager.js`](https://github.com/librechat-ai/librechat/blob/main/api/server/services/Runs/StreamRunManager.js) (Run streaming), [`api/server/services/Files`](https://github.com/librechat-ai/librechat/tree/main/api/server/services/Files) (File workflows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Client experience"]
  node_webapp["Chat UI<br/>[App.jsx]"]
  node_streamui["Stream handling"]
  node_data["Data service<br/>[data-service.ts]"]
  node_artifacts["Code artifacts<br/>[Artifacts.tsx]"]
end

subgraph group_runtime["Conversation runtime"]
  node_routes["API routes<br/>[index.js]"]
  node_chatcontrollers["Chat controllers"]
  node_runmanager["Run streaming"]
  node_modelclient["Model clients<br/>[BaseClient.js]"]
end

subgraph group_capabilities["Tools and capabilities"]
  node_agents["Agents"]
  node_tools["Tools and search"]
  node_mcp["MCP integration"]
  node_files["File workflows"]
  node_code["Code execution"]
  node_schedules["Schedules<br/>[engine.ts]"]
end

subgraph group_platform["Identity and platform"]
  node_auth["Authentication<br/>[AuthService.js]"]
  node_database[("Application data<br/>[models.js]")]
  node_observability["Tracing and insights<br/>[traces.js]"]
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_webapp -.->|"requests data"| node_data
node_data -.->|"calls API"| node_routes
node_routes -.->|"routes chat"| node_chatcontrollers
node_chatcontrollers -.->|"starts runs"| node_runmanager
node_runmanager -.->|"generates responses"| node_modelclient
node_runmanager -.->|"streams events"| node_streamui
node_agents -->|"uses tools"| node_tools
node_agents -->|"supports MCP"| node_mcp
node_tools -.->|"searches files"| node_files
node_agents -->|"runs code"| node_code
node_user -->|"uploads attachments"| node_files
node_user -->|"configures runs"| node_schedules
node_auth -.->|"stores sessions"| node_database
node_files -.->|"stores metadata"| node_database
node_webapp -->|"previews output"| node_artifacts
node_user -->|"views traces"| node_observability

click node_webapp "https://github.com/librechat-ai/librechat/blob/main/client/src/App.jsx"
click node_streamui "https://github.com/librechat-ai/librechat/blob/main/client/src/hooks/SSE/useEventHandlers.ts"
click node_data "https://github.com/librechat-ai/librechat/blob/main/packages/data-provider/src/data-service.ts"
click node_routes "https://github.com/librechat-ai/librechat/blob/main/api/server/routes/index.js"
click node_chatcontrollers "https://github.com/librechat-ai/librechat/tree/main/api/server/controllers/assistants"
click node_runmanager "https://github.com/librechat-ai/librechat/blob/main/api/server/services/Runs/StreamRunManager.js"
click node_modelclient "https://github.com/librechat-ai/librechat/blob/main/api/app/clients/BaseClient.js"
click node_agents "https://github.com/librechat-ai/librechat/tree/main/api/server/controllers/agents"
click node_tools "https://github.com/librechat-ai/librechat/tree/main/api/server/services/Tools"
click node_mcp "https://github.com/librechat-ai/librechat/tree/main/packages/api/src/mcp"
click node_files "https://github.com/librechat-ai/librechat/tree/main/api/server/services/Files"
click node_code "https://github.com/librechat-ai/librechat/tree/main/api/server/services/Files/Code"
click node_schedules "https://github.com/librechat-ai/librechat/blob/main/packages/api/src/schedules/engine.ts"
click node_auth "https://github.com/librechat-ai/librechat/blob/main/api/server/services/AuthService.js"
click node_database "https://github.com/librechat-ai/librechat/blob/main/api/db/models.js"
click node_artifacts "https://github.com/librechat-ai/librechat/blob/main/client/src/components/Artifacts/Artifacts.tsx"
click node_observability "https://github.com/librechat-ai/librechat/blob/main/api/server/routes/traces.js"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_webapp,node_streamui,node_data,node_artifacts,node_user toneBlue
class node_routes,node_chatcontrollers,node_runmanager,node_modelclient toneAmber
class node_agents,node_tools,node_mcp,node_files,node_code,node_schedules toneMint
class node_auth,node_database,node_observability toneRose
```

## Components

### Client experience

- [Chat UI](https://github.com/librechat-ai/librechat/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Stream handling](https://github.com/librechat-ai/librechat/blob/main/client/src/hooks/SSE/useEventHandlers.ts): `client/src/hooks/SSE/useEventHandlers.ts`
- [Data service](https://github.com/librechat-ai/librechat/blob/main/packages/data-provider/src/data-service.ts): `packages/data-provider/src/data-service.ts`
- [Code artifacts](https://github.com/librechat-ai/librechat/blob/main/client/src/components/Artifacts/Artifacts.tsx): `client/src/components/Artifacts/Artifacts.tsx`

### Conversation runtime

- [API routes](https://github.com/librechat-ai/librechat/blob/main/api/server/routes/index.js): `api/server/routes/index.js`
- [Chat controllers](https://github.com/librechat-ai/librechat/tree/main/api/server/controllers/assistants): `api/server/controllers/assistants`
- [Run streaming](https://github.com/librechat-ai/librechat/blob/main/api/server/services/Runs/StreamRunManager.js): `api/server/services/Runs/StreamRunManager.js`
- [Model clients](https://github.com/librechat-ai/librechat/blob/main/api/app/clients/BaseClient.js): `api/app/clients/BaseClient.js`

### Tools and capabilities

- [Agents](https://github.com/librechat-ai/librechat/tree/main/api/server/controllers/agents): `api/server/controllers/agents`
- [Tools and search](https://github.com/librechat-ai/librechat/tree/main/api/server/services/Tools): `api/server/services/Tools`
- [MCP integration](https://github.com/librechat-ai/librechat/tree/main/packages/api/src/mcp): `packages/api/src/mcp`
- [File workflows](https://github.com/librechat-ai/librechat/tree/main/api/server/services/Files): `api/server/services/Files`
- [Code execution](https://github.com/librechat-ai/librechat/tree/main/api/server/services/Files/Code): `api/server/services/Files/Code`
- [Schedules](https://github.com/librechat-ai/librechat/blob/main/packages/api/src/schedules/engine.ts): `packages/api/src/schedules/engine.ts`

### Identity and platform

- [Authentication](https://github.com/librechat-ai/librechat/blob/main/api/server/services/AuthService.js): `api/server/services/AuthService.js`
- [Application data](https://github.com/librechat-ai/librechat/blob/main/api/db/models.js): `api/db/models.js`
- [Tracing and insights](https://github.com/librechat-ai/librechat/blob/main/api/server/routes/traces.js): `api/server/routes/traces.js`

### Other components

- **User**

## Connections

- User → Chat UI: uses (evidence: `README.md`)
- Chat UI → Data service: requests data
- Data service → API routes: calls API
- API routes → Chat controllers: routes chat
- Chat controllers → Run streaming: starts runs
- Run streaming → Model clients: generates responses
- Run streaming → Stream handling: streams events
- Agents → Tools and search: uses tools (evidence: `README.md`)
- Agents → MCP integration: supports MCP (evidence: `README.md`)
- Tools and search → File workflows: searches files
- Agents → Code execution: runs code (evidence: `README.md`)
- User → File workflows: uploads attachments (evidence: `README.md`)
- User → Schedules: configures runs (evidence: `README.md`)
- Authentication → Application data: stores sessions
- File workflows → Application data: stores metadata
- Chat UI → Code artifacts: previews output (evidence: `README.md`)
- User → Tracing and insights: views traces (evidence: `README.md`)