# kapo-solothurn-ai-poc/librechat architecture

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

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

## Overview

##### Project type and purpose
- LibreChat is a full-stack, open-source AI chat platform built as a monorepo.
- It includes a React/Vite single-page application (client/) and a Node.js/Express API server (api/) plus auxiliary packages (packages/data-provider, packages/mcp).
- Purpose: provide ChatGPT-style UI, multi-model AI integration, agents/tools, code execution, file handling, and multi-user, token-based access.

##### File structure
Top-level directories
- client/ — React-based SPA: UI components, contexts, hooks, data-provider queries/mutations, styling, routes, tests.
- api/ — Backend monolith:
– app/clients: adapters for OpenAI, Anthropic, Google, Ollama, plugins, streaming, agents & tools.
– cache/: Redis/Mongo caches & keyv wrappers.
– config/: app-wide configuration (paths, parsers, logging).
– lib/db: MongoDB connection.
– models/: Mongoose schemas and business logic (User, Conversation, Token, ToolCall, etc).
– server/: Express controllers, routes, middleware, services (AuthService, AgentService, RunManager, FileService, TokenService...).
– utils/: helpers, email templates, queue, streaming, importer.
- packages/ — shared libraries:
– data-provider: client data access layer (generic SDK for GraphQL/REST).
– mcp: Model Context Protocol tools.
- charts/, .devcontainer/, Dockerfile(s), helm charts: Docker/Kubernetes deployment.
- e2e/, test/, jest.config: end-to-end and unit test frameworks.
- config/: CLI scripts for admin tasks (user creation, balance, banner).
- utils/docker/, deploy-compose.yml: DevOps scripts.

##### README for additional insights
- Stack: React + Vite + Tailwind (client), Node.js + Express + Mongoose + Redis + Meilisearch (api), Docker, Helm, Kubernetes.
- Features: AI endpoint abstraction, agent/tool plugin system, code interpreter sandbox, file uploads, SSE streaming.
- External integrations: OAuth2 (GitHub, Google, Apple, LDAP), AI providers (OpenAI, Anthropic, AWS Bedrock, Google Vertex AI, custom endpoints).
- Multi-tenant, token-based moderation, search, internationalization.

##### Essential details
- Major folder as a component (client/src/providers, api/app/clients, api/server/services, api/models).
- Don’t omit the shared packages (data-provider SDK, mcp)—they form part of the extensibility architecture.
- Deployment targets: Docker containers, Kubernetes pods via Helm.
- CI/CD pipelines (.github/workflows) externally if needed for a deployment view.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User & Browser"
        User["User"]:::user
        Browser["Browser"]:::external
        User -->|HTTPS/WebSocket| Browser
    end

    subgraph "Frontend (client)"
        SPA["React/Vite SPA"]:::frontend
    end
    Browser -->|REST/SSE| SPA
    click SPA "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/client/"

    subgraph "Shared Packages"
        DP["Data-Provider SDK"]:::shared
        MCP["MCP Tools"]:::shared
    end
    SPA --> DP
    SPA --> MCP
    click DP "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/packages/data-provider/"
    click MCP "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/packages/mcp/"

    subgraph "API Gateway (Express)"
        Index["index.js"]:::backend
        Routes["routes/"]:::backend
    end
    SPA -->|REST/SSE| Index
    Index --> Routes
    click Index "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/server/index.js"
    click Routes "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/api/server/routes/"

    subgraph "Business Logic & Core Services"
        Auth["AuthService"]:::backend
        Model["ModelService"]:::backend
        AgentRun["RunManager"]:::backend
        FileServ["FileService"]:::backend
        TokenServ["TokenService"]:::backend
    end
    Routes --> Auth
    Routes --> Model
    Routes --> AgentRun
    Routes --> FileServ
    Routes --> TokenServ
    click Auth "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/server/services/AuthService.js"
    click Model "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/server/services/ModelService.js"
    click AgentRun "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/server/services/Runs/RunManager.js"
    click FileServ "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/api/server/services/Files/"
    click TokenServ "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/server/services/TokenService.js"

    subgraph "Ports & Adapters (AI Clients)"
        OpenAI["OpenAIClient"]:::adapter
        Anthropic["AnthropicClient"]:::adapter
        Google["GoogleClient"]:::adapter
        Ollama["OllamaClient"]:::adapter
        Plugins["PluginsClient"]:::adapter
        AgentsTools["Agents/Tools"]:::adapter
    end
    AgentRun --> OpenAI
    AgentRun --> Anthropic
    AgentRun --> Google
    AgentRun --> Ollama
    AgentRun --> Plugins
    AgentRun --> AgentsTools
    click OpenAI "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/app/clients/OpenAIClient.js"
    click Anthropic "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/app/clients/AnthropicClient.js"
    click Google "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/app/clients/GoogleClient.js"
    click Ollama "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/app/clients/OllamaClient.js"
    click Plugins "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/app/clients/PluginsClient.js"
    click AgentsTools "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/api/app/clients/agents/"

    subgraph "Data Layer & External"
        MongoConn["connectDb.js"]:::database
        Schemas["Models (api/models)"]:::database
        Redis["Redis Cache"]:::database
        Keyv["Keyv Wrappers"]:::database
        Meili["Meilisearch"]:::database
        FileStore["File Storage"]:::database
        AuthProviders["OAuth/LDAP Providers"]:::external
        AIEndpoints["AI Endpoints"]:::external
    end
    Auth --> MongoConn
    Model --> Schemas
    FileServ --> FileStore
    TokenServ --> Redis
    TokenServ --> Keyv
    Auth --> AuthProviders
    OpenAI --> AIEndpoints
    Anthropic --> AIEndpoints
    Google --> AIEndpoints
    Ollama --> AIEndpoints
    click MongoConn "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/lib/db/connectDb.js"
    click Schemas "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/api/models/"
    click Redis "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/cache/redis.js"
    click Keyv "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/cache/keyvRedis.js"
    Meili --> MeiliLogger["meiliLogger.js"]:::backend
    click MeiliLogger "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/config/meiliLogger.js"

    subgraph "Third-Party Auth Strategies"
        GitHub["GitHub Strategy"]:::external
        GoogleStr["Google Strategy"]:::external
        Apple["Apple Strategy"]:::external
        LDAP["LDAP Strategy"]:::external
        JWT["JWT Strategy"]:::external
    end
    AuthProviders --> GitHub
    AuthProviders --> GoogleStr
    AuthProviders --> Apple
    AuthProviders --> LDAP
    AuthProviders --> JWT
    click GitHub "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/strategies/githubStrategy.js"
    click GoogleStr "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/strategies/googleStrategy.js"
    click Apple "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/strategies/appleStrategy.js"
    click LDAP "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/strategies/ldapStrategy.js"
    click JWT "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/api/strategies/jwtStrategy.js"

    subgraph "DevOps / Deployment"
        Docker["Docker & Compose"]:::infra
        Helm["K8s Helm Charts"]:::infra
        DevContainer["DevContainer"]:::infra
        InfraFlow["CI/CD"]:::infra
    end
    Docker --> Helm
    Helm --> InfraFlow
    DevContainer -.-> InfraFlow
    click Docker "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/Dockerfile"
    click Docker "https://github.com/kapo-solothurn-ai-poc/librechat/blob/main/docker-compose.yml"
    click Helm "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/charts/librechat/"
    click DevContainer "https://github.com/kapo-solothurn-ai-poc/librechat/tree/main/.devcontainer/"

    classDef user fill:#cee5f2,stroke:#0366d6,color:#0366d6
    classDef frontend fill:#b3d4fc,stroke:#1e40af,color:#1e40af
    classDef backend fill:#d1fae5,stroke:#047857,color:#047857
    classDef adapter fill:#fcebd0,stroke:#d97706,color:#d97706,stroke-dasharray: 2 2
    classDef database fill:#ffe4e6,stroke:#be123c,color:#be123c,stroke-dasharray: 2 2
    classDef external fill:#e0e0e0,stroke:#4b5563,color:#4b5563,stroke-dasharray: 2 2
    classDef shared fill:#f3e8ff,stroke:#7c3aed,color:#7c3aed
    classDef infra fill:#f0f9ff,stroke:#0369a1,color:#0369a1
```
