# arafa1974/librechat architecture

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

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

## Overview

LibreChat is a self-hosted, full-stack AI chat application. A user works through the browser UI to converse with configured model endpoints; the product also supports Agents, tools and MCP, files, schedules, authentication, and observability. The tree and README establish these major capabilities, while sampled source confirms selected internal relationships: trigger dispatch, stream job management, and the data-provider query layer. Many domain routes and integrations were not sampled, so their links are marked unverified rather than presented as inspected call paths.

Main entry points: [`api/server/routes/index.js`](https://github.com/arafa1974/librechat/blob/main/api/server/routes/index.js) (HTTP API), [`api/server/services/Runs/StreamRunManager.js`](https://github.com/arafa1974/librechat/blob/main/api/server/services/Runs/StreamRunManager.js) (Run manager), [`api/server/controllers/agents/request.js`](https://github.com/arafa1974/librechat/blob/main/api/server/controllers/agents/request.js) (Agent API), [`packages/api/src/agents/triggers/engine.ts`](https://github.com/arafa1974/librechat/blob/main/packages/api/src/agents/triggers/engine.ts) (Trigger engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Chat experience"]
  node_webapp["Web application<br/>[App.jsx]"]
  node_chatui["Chat interface<br/>[ChatView.tsx]"]
  node_datahooks["Data query hooks"]
  node_dataservice["API data service<br/>[data-service.ts]"]
end

subgraph group_conversation["Conversation runtime"]
  node_chatflow["Chat endpoints<br/>[convos.js]"]
  node_runmanager["Run manager"]
  node_generation["Generation jobs"]
  node_jobstore[("Job store")]
  node_models["Model clients<br/>[BaseClient.js]"]
end

subgraph group_agents["Agents and tools"]
  node_agentapi["Agent API<br/>[request.js]"]
  node_triggerengine["Trigger engine<br/>[engine.ts]"]
  node_triggerdispatch["Trigger dispatch<br/>[dispatch.ts]"]
  node_toolservice["Tools and MCP<br/>[ToolService.js]"]
  node_schedules["Schedules<br/>[engine.ts]"]
end

subgraph group_platform["Platform services"]
  node_api["HTTP API<br/>[index.js]"]
  node_files["File services<br/>[operations.js]"]
  node_storage["File storage<br/>[storage.ts]"]
  node_database[("Application database<br/>[connect.js]")]
  node_auth["Authentication<br/>[AuthService.js]"]
end

subgraph group_integration["External integrations"]
  node_gateway["Channel gateway<br/>[app.ts]"]
  node_modelproviders["Model providers"]
  node_mcpservers["MCP servers"]
  node_slack["Slack"]
end

node_user(("User"))

node_user -.->|"uses"| node_webapp
node_webapp -.->|"renders"| node_chatui
node_chatui -.->|"requests data"| node_datahooks
node_datahooks -->|"calls"| node_dataservice
node_dataservice -.->|"HTTP requests"| node_api
node_api -.->|"routes"| node_chatflow
node_chatflow -.->|"starts runs"| node_runmanager
node_runmanager -.->|"manages jobs"| node_generation
node_generation -->|"persists jobs"| node_jobstore
node_runmanager -.->|"invokes"| node_models
node_models -.->|"calls"| node_modelproviders
node_api -.->|"authenticates"| node_auth
node_api -.->|"uses"| node_database
node_api -.->|"serves file operations"| node_files
node_files -.->|"delegates storage"| node_storage
node_storage -.->|"coordinates metadata"| node_database
node_api -.->|"routes agent requests"| node_agentapi
node_agentapi -.->|"queues triggers"| node_triggerengine
node_triggerengine -->|"dispatches"| node_triggerdispatch
node_triggerdispatch -.->|"invokes handlers"| node_agentapi
node_api -.->|"serves tool requests"| node_toolservice
node_toolservice -.->|"connects tools"| node_mcpservers
node_schedules -.->|"fires agent triggers"| node_triggerengine
node_gateway -.->|"handles channel events"| node_slack

click node_webapp "https://github.com/arafa1974/librechat/blob/main/client/src/App.jsx"
click node_chatui "https://github.com/arafa1974/librechat/blob/main/client/src/components/Chat/ChatView.tsx"
click node_datahooks "https://github.com/arafa1974/librechat/blob/main/packages/data-provider/src/react-query/react-query-service.ts"
click node_dataservice "https://github.com/arafa1974/librechat/blob/main/packages/data-provider/src/data-service.ts"
click node_api "https://github.com/arafa1974/librechat/blob/main/api/server/routes/index.js"
click node_chatflow "https://github.com/arafa1974/librechat/blob/main/api/server/routes/convos.js"
click node_runmanager "https://github.com/arafa1974/librechat/blob/main/api/server/services/Runs/StreamRunManager.js"
click node_generation "https://github.com/arafa1974/librechat/blob/main/packages/api/src/stream/GenerationJobManager.ts"
click node_jobstore "https://github.com/arafa1974/librechat/blob/main/packages/api/src/stream/implementations/InMemoryJobStore.ts"
click node_models "https://github.com/arafa1974/librechat/blob/main/api/app/clients/BaseClient.js"
click node_files "https://github.com/arafa1974/librechat/blob/main/api/server/services/Files/operations.js"
click node_storage "https://github.com/arafa1974/librechat/blob/main/packages/api/src/files/storage.ts"
click node_database "https://github.com/arafa1974/librechat/blob/main/api/db/connect.js"
click node_auth "https://github.com/arafa1974/librechat/blob/main/api/server/services/AuthService.js"
click node_agentapi "https://github.com/arafa1974/librechat/blob/main/api/server/controllers/agents/request.js"
click node_triggerengine "https://github.com/arafa1974/librechat/blob/main/packages/api/src/agents/triggers/engine.ts"
click node_triggerdispatch "https://github.com/arafa1974/librechat/blob/main/packages/api/src/agents/triggers/dispatch.ts"
click node_toolservice "https://github.com/arafa1974/librechat/blob/main/api/server/services/ToolService.js"
click node_schedules "https://github.com/arafa1974/librechat/blob/main/packages/api/src/schedules/engine.ts"
click node_gateway "https://github.com/arafa1974/librechat/blob/main/packages/channel-gateway/src/app.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_webapp,node_chatui,node_datahooks,node_dataservice,node_user toneBlue
class node_chatflow,node_runmanager,node_generation,node_jobstore,node_models toneAmber
class node_agentapi,node_triggerengine,node_triggerdispatch,node_toolservice,node_schedules toneMint
class node_api,node_files,node_storage,node_database,node_auth toneRose
class node_gateway,node_modelproviders,node_mcpservers,node_slack toneIndigo
```

## Components

### Chat experience

- [Web application](https://github.com/arafa1974/librechat/blob/main/client/src/App.jsx): `client/src/App.jsx`
- [Chat interface](https://github.com/arafa1974/librechat/blob/main/client/src/components/Chat/ChatView.tsx): `client/src/components/Chat/ChatView.tsx`
- [Data query hooks](https://github.com/arafa1974/librechat/blob/main/packages/data-provider/src/react-query/react-query-service.ts): `packages/data-provider/src/react-query/react-query-service.ts`
- [API data service](https://github.com/arafa1974/librechat/blob/main/packages/data-provider/src/data-service.ts): `packages/data-provider/src/data-service.ts`

### Conversation runtime

- [Chat endpoints](https://github.com/arafa1974/librechat/blob/main/api/server/routes/convos.js): `api/server/routes/convos.js`
- [Run manager](https://github.com/arafa1974/librechat/blob/main/api/server/services/Runs/StreamRunManager.js): `api/server/services/Runs/StreamRunManager.js`
- [Generation jobs](https://github.com/arafa1974/librechat/blob/main/packages/api/src/stream/GenerationJobManager.ts): `packages/api/src/stream/GenerationJobManager.ts`
- [Job store](https://github.com/arafa1974/librechat/blob/main/packages/api/src/stream/implementations/InMemoryJobStore.ts): `packages/api/src/stream/implementations/InMemoryJobStore.ts`
- [Model clients](https://github.com/arafa1974/librechat/blob/main/api/app/clients/BaseClient.js): `api/app/clients/BaseClient.js`

### Agents and tools

- [Agent API](https://github.com/arafa1974/librechat/blob/main/api/server/controllers/agents/request.js): `api/server/controllers/agents/request.js`
- [Trigger engine](https://github.com/arafa1974/librechat/blob/main/packages/api/src/agents/triggers/engine.ts): `packages/api/src/agents/triggers/engine.ts`
- [Trigger dispatch](https://github.com/arafa1974/librechat/blob/main/packages/api/src/agents/triggers/dispatch.ts): `packages/api/src/agents/triggers/dispatch.ts`
- [Tools and MCP](https://github.com/arafa1974/librechat/blob/main/api/server/services/ToolService.js): `api/server/services/ToolService.js`
- [Schedules](https://github.com/arafa1974/librechat/blob/main/packages/api/src/schedules/engine.ts): `packages/api/src/schedules/engine.ts`

### Platform services

- [HTTP API](https://github.com/arafa1974/librechat/blob/main/api/server/routes/index.js): `api/server/routes/index.js`
- [File services](https://github.com/arafa1974/librechat/blob/main/api/server/services/Files/operations.js): `api/server/services/Files/operations.js`
- [File storage](https://github.com/arafa1974/librechat/blob/main/packages/api/src/files/storage.ts): `packages/api/src/files/storage.ts`
- [Application database](https://github.com/arafa1974/librechat/blob/main/api/db/connect.js): `api/db/connect.js`
- [Authentication](https://github.com/arafa1974/librechat/blob/main/api/server/services/AuthService.js): `api/server/services/AuthService.js`

### External integrations

- [Channel gateway](https://github.com/arafa1974/librechat/blob/main/packages/channel-gateway/src/app.ts): `packages/channel-gateway/src/app.ts`
- **Model providers**
- **MCP servers**
- **Slack**

### Other components

- **User**

## Connections

- User → Web application: uses (evidence: `README.md`)
- Web application → Chat interface: renders
- Chat interface → Data query hooks: requests data
- Data query hooks → API data service: calls (evidence: `packages/data-provider/src/react-query/react-query-service.ts`)
- API data service → HTTP API: HTTP requests
- HTTP API → Chat endpoints: routes
- Chat endpoints → Run manager: starts runs
- Run manager → Generation jobs: manages jobs
- Generation jobs → Job store: persists jobs (evidence: `packages/api/src/stream/GenerationJobManager.ts`)
- Run manager → Model clients: invokes
- Model clients → Model providers: calls (evidence: `README.md`)
- HTTP API → Authentication: authenticates
- HTTP API → Application database: uses
- HTTP API → File services: serves file operations
- File services → File storage: delegates storage
- File storage → Application database: coordinates metadata
- HTTP API → Agent API: routes agent requests
- Agent API → Trigger engine: queues triggers
- Trigger engine → Trigger dispatch: dispatches (evidence: `packages/api/src/agents/triggers/engine.ts`)
- Trigger dispatch → Agent API: invokes handlers
- HTTP API → Tools and MCP: serves tool requests
- Tools and MCP → MCP servers: connects tools (evidence: `README.md`)
- Schedules → Trigger engine: fires agent triggers (evidence: `packages/api/src/schedules/engine.ts`)
- Channel gateway → Slack: handles channel events (evidence: `README.md`)
