# danny-avila/librechat architecture

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

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

## Overview

LibreChat is a self-hosted multi-model conversational platform with chat, Agents, Assistants, tools, files, MCP, artifacts, and automation. The principal workflow is: a user submits chat content, authenticated API routes create a run, the run invokes a configured model and optional tools, state is persisted, and streamed events update the client conversation. The graph combines documented capabilities with sampled implementation evidence; several broad subsystems are represented by their exact enclosing paths because their internals were not sampled.

Main entry points: [`api/server/services/Runs/RunManager.js`](https://github.com/danny-avila/librechat/blob/main/api/server/services/Runs/RunManager.js) (Run Manager), [`client/src/components/Chat/ChatView.tsx`](https://github.com/danny-avila/librechat/blob/main/client/src/components/Chat/ChatView.tsx) (Chat UI), [`api/server/routes/messages.js`](https://github.com/danny-avila/librechat/blob/main/api/server/routes/messages.js) (Chat Routes), [`api/app/clients/tools/util/handleTools.js`](https://github.com/danny-avila/librechat/blob/main/api/app/clients/tools/util/handleTools.js) (Tool Runtime)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Client Experience"]
  node_chat_ui["Chat UI<br/>[ChatView.tsx]"]
  node_query_intake["Query Intake<br/>[useQueryParams.ts]"]
  node_sse_events["SSE Events"]
  node_mcp_manager["MCP Manager"]
end

subgraph group_gateway["API Gateway"]
  node_auth["Auth Middleware<br/>[requireJwtAuth.js]"]
  node_chat_routes["Chat Routes<br/>[messages.js]"]
  node_agent_management["Agent Management<br/>[management.js]"]
end

subgraph group_runtime["AI Runtime"]
  node_run_manager["Run Manager<br/>[RunManager.js]"]
  node_stream_runs["Stream Runs"]
  node_model_clients["Model Clients<br/>[index.js]"]
  node_tool_runtime["Tool Runtime<br/>[handleTools.js]"]
  node_mcp_service["MCP Service<br/>[MCP.js]"]
  node_structured_tools["Structured Tools<br/>[GoogleSearch.js]"]
end

subgraph group_data["Data Services"]
  node_file_pipeline["File Pipeline<br/>[index.js]"]
  node_conversation_store[("Conversation Store<br/>[models.js]")]
  node_file_storage[("File Storage")]
  node_data_provider["Data Provider"]
end

subgraph group_automation["Automation"]
  node_schedule_engine["Schedule Engine<br/>[engine.ts]"]
  node_trigger_engine["Agent Triggers<br/>[engine.ts]"]
end

node_user(("User"))
node_model_providers["Model Providers"]
node_search_services["Search Services"]
node_mcp_servers["MCP Servers"]

node_user -->|"submits prompt"| node_chat_ui
node_chat_ui -->|"sends message"| node_chat_routes
node_chat_ui -->|"uploads files"| node_file_pipeline
node_query_intake -->|"applies settings"| node_chat_ui
node_chat_routes -->|"requires identity"| node_auth
node_auth -->|"reads account"| node_conversation_store
node_chat_routes -->|"creates run"| node_run_manager
node_run_manager -->|"invokes model"| node_model_clients
node_model_clients -->|"calls provider"| node_model_providers
node_run_manager -->|"dispatches tools"| node_tool_runtime
node_tool_runtime -->|"runs tool"| node_structured_tools
node_structured_tools -.->|"performs search"| node_search_services
node_tool_runtime -->|"dispatches MCP"| node_mcp_service
node_mcp_service -.->|"calls server"| node_mcp_servers
node_run_manager -->|"persists state"| node_conversation_store
node_run_manager -->|"streams run"| node_stream_runs
node_stream_runs -->|"emits events"| node_sse_events
node_sse_events -->|"updates view"| node_chat_ui
node_file_pipeline -->|"stores files"| node_file_storage
node_agent_management -->|"manages agents"| node_conversation_store
node_mcp_manager -->|"queries status"| node_data_provider
node_data_provider -->|"requests MCP"| node_mcp_service
node_schedule_engine -->|"fires runs"| node_run_manager
node_trigger_engine -->|"dispatches agents"| node_run_manager

click node_chat_ui "https://github.com/danny-avila/librechat/blob/main/client/src/components/Chat/ChatView.tsx"
click node_query_intake "https://github.com/danny-avila/librechat/blob/main/client/src/hooks/Input/useQueryParams.ts"
click node_sse_events "https://github.com/danny-avila/librechat/blob/main/client/src/hooks/SSE/useEventHandlers.ts"
click node_mcp_manager "https://github.com/danny-avila/librechat/blob/main/client/src/hooks/MCP/useMCPServerManager.ts"
click node_auth "https://github.com/danny-avila/librechat/blob/main/api/server/middleware/requireJwtAuth.js"
click node_chat_routes "https://github.com/danny-avila/librechat/blob/main/api/server/routes/messages.js"
click node_agent_management "https://github.com/danny-avila/librechat/blob/main/api/server/routes/agents/management.js"
click node_run_manager "https://github.com/danny-avila/librechat/blob/main/api/server/services/Runs/RunManager.js"
click node_stream_runs "https://github.com/danny-avila/librechat/blob/main/api/server/services/Runs/StreamRunManager.js"
click node_model_clients "https://github.com/danny-avila/librechat/blob/main/api/app/clients/index.js"
click node_tool_runtime "https://github.com/danny-avila/librechat/blob/main/api/app/clients/tools/util/handleTools.js"
click node_mcp_service "https://github.com/danny-avila/librechat/blob/main/api/server/services/MCP.js"
click node_structured_tools "https://github.com/danny-avila/librechat/blob/main/api/app/clients/tools/structured/GoogleSearch.js"
click node_file_pipeline "https://github.com/danny-avila/librechat/blob/main/api/server/services/Files/index.js"
click node_conversation_store "https://github.com/danny-avila/librechat/blob/main/api/db/models.js"
click node_data_provider "https://github.com/danny-avila/librechat/blob/main/packages/data-provider/src/react-query/react-query-service.ts"
click node_schedule_engine "https://github.com/danny-avila/librechat/blob/main/packages/api/src/schedules/engine.ts"
click node_trigger_engine "https://github.com/danny-avila/librechat/blob/main/packages/api/src/agents/triggers/engine.ts"

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_chat_ui,node_query_intake,node_sse_events,node_mcp_manager,node_user toneBlue
class node_auth,node_chat_routes,node_agent_management toneAmber
class node_run_manager,node_stream_runs,node_model_clients,node_tool_runtime,node_mcp_service,node_structured_tools,node_mcp_servers toneMint
class node_file_pipeline,node_conversation_store,node_file_storage,node_data_provider toneRose
class node_schedule_engine,node_trigger_engine,node_model_providers,node_search_services toneIndigo
```

## Components

### Client Experience

- [Chat UI](https://github.com/danny-avila/librechat/blob/main/client/src/components/Chat/ChatView.tsx): `client/src/components/Chat/ChatView.tsx`
- [Query Intake](https://github.com/danny-avila/librechat/blob/main/client/src/hooks/Input/useQueryParams.ts): `client/src/hooks/Input/useQueryParams.ts`
- [SSE Events](https://github.com/danny-avila/librechat/blob/main/client/src/hooks/SSE/useEventHandlers.ts): `client/src/hooks/SSE/useEventHandlers.ts`
- [MCP Manager](https://github.com/danny-avila/librechat/blob/main/client/src/hooks/MCP/useMCPServerManager.ts): `client/src/hooks/MCP/useMCPServerManager.ts`

### API Gateway

- [Auth Middleware](https://github.com/danny-avila/librechat/blob/main/api/server/middleware/requireJwtAuth.js): `api/server/middleware/requireJwtAuth.js`
- [Chat Routes](https://github.com/danny-avila/librechat/blob/main/api/server/routes/messages.js): `api/server/routes/messages.js`
- [Agent Management](https://github.com/danny-avila/librechat/blob/main/api/server/routes/agents/management.js): `api/server/routes/agents/management.js`

### AI Runtime

- [Run Manager](https://github.com/danny-avila/librechat/blob/main/api/server/services/Runs/RunManager.js): `api/server/services/Runs/RunManager.js`
- [Stream Runs](https://github.com/danny-avila/librechat/blob/main/api/server/services/Runs/StreamRunManager.js): `api/server/services/Runs/StreamRunManager.js`
- [Model Clients](https://github.com/danny-avila/librechat/blob/main/api/app/clients/index.js): `api/app/clients/index.js`
- [Tool Runtime](https://github.com/danny-avila/librechat/blob/main/api/app/clients/tools/util/handleTools.js): `api/app/clients/tools/util/handleTools.js`
- [MCP Service](https://github.com/danny-avila/librechat/blob/main/api/server/services/MCP.js): `api/server/services/MCP.js`
- [Structured Tools](https://github.com/danny-avila/librechat/blob/main/api/app/clients/tools/structured/GoogleSearch.js): `api/app/clients/tools/structured/GoogleSearch.js`

### Data Services

- [File Pipeline](https://github.com/danny-avila/librechat/blob/main/api/server/services/Files/index.js): `api/server/services/Files/index.js`
- [Conversation Store](https://github.com/danny-avila/librechat/blob/main/api/db/models.js): `api/db/models.js`
- **File Storage**
- [Data Provider](https://github.com/danny-avila/librechat/blob/main/packages/data-provider/src/react-query/react-query-service.ts): `packages/data-provider/src/react-query/react-query-service.ts`

### Automation

- [Schedule Engine](https://github.com/danny-avila/librechat/blob/main/packages/api/src/schedules/engine.ts): `packages/api/src/schedules/engine.ts`
- [Agent Triggers](https://github.com/danny-avila/librechat/blob/main/packages/api/src/agents/triggers/engine.ts): `packages/api/src/agents/triggers/engine.ts`

### Other components

- **User**
- **Model Providers**
- **Search Services**
- **MCP Servers**

## Connections

- User → Chat UI: submits prompt
- Chat UI → Chat Routes: sends message
- Chat UI → File Pipeline: uploads files
- Query Intake → Chat UI: applies settings
- Chat Routes → Auth Middleware: requires identity
- Auth Middleware → Conversation Store: reads account
- Chat Routes → Run Manager: creates run
- Run Manager → Model Clients: invokes model
- Model Clients → Model Providers: calls provider
- Run Manager → Tool Runtime: dispatches tools
- Tool Runtime → Structured Tools: runs tool
- Structured Tools → Search Services: performs search
- Tool Runtime → MCP Service: dispatches MCP
- MCP Service → MCP Servers: calls server
- Run Manager → Conversation Store: persists state
- Run Manager → Stream Runs: streams run
- Stream Runs → SSE Events: emits events
- SSE Events → Chat UI: updates view
- File Pipeline → File Storage: stores files
- Agent Management → Conversation Store: manages agents
- MCP Manager → Data Provider: queries status
- Data Provider → MCP Service: requests MCP
- Schedule Engine → Run Manager: fires runs
- Agent Triggers → Run Manager: dispatches agents
