# nosportugal/librechat architecture

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

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

## Overview

##### Project type and purpose
- This is a full-stack, open-source AI chat platform (“LibreChat”) comprising:
- A React/Vite single-page application (client/)
- A Node.js/Express-style REST & SSE backend (api/)
- Supporting packages (data-provider, data-schemas, mcp)
- Infrastructure definitions (Docker, Helm charts, CI/CD workflows)
- Purpose: Provide a ChatGPT-inspired UI, multiple AI endpoints (OpenAI, Anthropic, Google, Bedrock, custom OpenAI-compatible), file upload & processing, agents/tool integrations, RAG (vector search) API, multi-user auth, caching, and vector DB retrieval.

##### File structure
- Top-level directories:
- client/ → React SPA, context providers, hooks, components, routes, store, styling, i18n
- api/ → controllers, routes, middleware, services, AI clients, models, cache, config, utils
- packages/ → shared libraries: data-provider (client/server GraphQL/REST client libs), data-schemas (Zod schemas), mcp (Model Context Protocol)
- helm/ → Kubernetes charts for main LibreChat and RAG API
- docker-compose & Dockerfiles → container definitions for client, api, vector service, DB, cache
- .github/ → CI/CD workflows, tests, release scripts

##### README for additional insights
- Multi-AI provider routing, code interpreter sandbox, agents & tools, RAG API link, file storage options, multi-auth (OAuth2, LDAP, email), cache usage, vector search.
- Deployment: Docker, Railway, Helm/K8s, Zeabur, Sealos.

a. Main components
- Frontend (React SPA)
- API Gateway / Backend (Express server)
- RAG API Service (vector search microservice)
- Data Stores:
- Primary DB: MongoDB (api/lib/db)
- Cache: Redis / Keyv stores
- Vector DB: (e.g., Pinecone, Qdrant, Weaviate) behind RAG API
- File Storage: S3, Azure Blob, Firebase, Local FS
- Authentication & Authorization: Passport strategies, OAuth2, LDAP
- External AI Providers: OpenAI, Anthropic, Google Vertex, AWS Bedrock, Azure, custom endpoints
- CI/CD & Infrastructure: GitHub Actions, Docker, Helm, Kubernetes

b. Relationships & interactions
- Browser → Frontend UI (React)
- Frontend → Backend API (HTTPS for REST calls; EventSource/SSE for streaming chat)
- Backend → MongoDB (CRUD for users, conversations, messages, tokens, plugins, presets)
- Backend → Redis/Keyv for rate-limiting, caching responses, session data
- Backend → File Storage services for upload/download
- Backend → External AI endpoints via api/app/clients/*
- Backend → RAG API Service to perform vector searches (SSE or REST)
- RAG API Service → Vector DB for similarity search
- CI/CD → Build & push Docker images → Helm → Kubernetes clusters

c. Architectural patterns & design principles
- Layered architecture: Presentation (client/) → Application (controllers/routes/services) → Data (models, db connectors)
- Microservice for RAG vector search (separate Helm chart)
- Adapter/Client factories for each AI provider (implements Strategy pattern)
- Middleware chain (Express) for auth, rate-limit, validation, error handling
- Context separation in front end via React Context & React-Query (data-provider)
- CICD pipeline automates lint, test, build, deploy

d. Key technologies & frameworks
- Frontend: React, Vite, TypeScript, React-Query, Tailwind, i18next
- Backend: Node.js, Express (or similar), TypeScript/JavaScript, Mongoose, ioredis, Keyv, Passport.js
- Vector Search: custom RAG API, Vector DB of choice
- File Handling: Multer, S3/Azure/Firebase SDKs
- CI/CD: GitHub Actions, Docker, Helm charts, Kubernetes

##### Detail without overthinking
- Multiple AI clients as separate adapters under the “AI Providers” cluster.
- Crucial architectural elements at the component level for clarity.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Frontend Layer
    subgraph "Frontend Layer"
        F["React SPA"]:::frontend
    end

    %% Backend API Layer
    subgraph "Backend API Layer"
        server["Express API"]:::backend
        controllers["API Controllers"]:::backend
        routes["API Routes"]:::backend
        middleware["Middleware"]:::backend
        services["Services Layer"]:::backend
        dataaccess["Data Access (Mongoose Models)"]:::backend
        dbconnector["DB Connector"]:::backend
        strategies["Auth Strategies"]:::backend
    end

    %% Shared Packages
    subgraph "Shared Packages"
        dp["data-provider"]:::backend
        ds["data-schemas"]:::backend
        mcp["mcp"]:::backend
    end

    %% AI Clients Adapters
    subgraph "AI Clients Adapters"
        aiclient["API Clients"]:::backend
        agents["Agents Adapters"]:::backend
        tools["Tools Adapters"]:::backend
    end

    %% Data Stores
    subgraph "Data Stores"
        mongo["MongoDB"]:::db
        redis["Redis Cache"]:::db
        vectordb["Vector DB"]:::db
        filestorage["File Storage"]:::storage
    end

    %% RAG Microservice
    subgraph "RAG Microservice"
        rag["RAG API Service"]:::backend
    end

    %% AI Providers
    subgraph "AI Providers"
        openai["OpenAI"]:::external
        anthropic["Anthropic"]:::external
        google["Google Vertex"]:::external
        bedrock["AWS Bedrock"]:::external
        customai["Custom AI"]:::external
    end

    %% CI/CD & Infrastructure
    subgraph "CI/CD & Infra"
        ci["GitHub Actions"]:::infra
        docker["Docker Compose & Dockerfiles"]:::infra
        helmmain["Helm Chart: LibreChat"]:::infra
        helmrag["Helm Chart: LibreChat RAG API"]:::infra
        k8s["Kubernetes"]:::infra
    end

    %% Connections
    F -->|"HTTPS / SSE"| server
    server --> controllers
    server --> routes
    server --> middleware
    middleware --> strategies
    controllers --> services
    services --> dataaccess
    server --> dbconnector
    dbconnector --> mongo
    server --> redis
    server --> filestorage
    server --> rag
    services --> openai
    services --> anthropic
    services --> google
    services --> bedrock
    services --> customai
    services --> dp
    services --> ds
    services --> mcp
    services --> aiclient
    aiclient --> agents
    aiclient --> tools
    rag --> vectordb

    ci --> docker
    docker --> helmmain
    docker --> helmrag
    helmmain --> k8s
    helmrag --> k8s

    %% Click Events
    click F "https://github.com/nosportugal/librechat/tree/main/client/"
    click server "https://github.com/nosportugal/librechat/blob/main/api/server/index.js"
    click controllers "https://github.com/nosportugal/librechat/tree/main/api/server/controllers/"
    click routes "https://github.com/nosportugal/librechat/tree/main/api/server/routes/"
    click middleware "https://github.com/nosportugal/librechat/tree/main/api/server/middleware/"
    click services "https://github.com/nosportugal/librechat/tree/main/api/server/services/"
    click dataaccess "https://github.com/nosportugal/librechat/tree/main/api/models/"
    click dbconnector "https://github.com/nosportugal/librechat/blob/main/api/lib/db/connectDb.js"
    click redis "https://github.com/nosportugal/librechat/tree/main/api/cache/"
    click aiclient "https://github.com/nosportugal/librechat/tree/main/api/app/clients/"
    click agents "https://github.com/nosportugal/librechat/tree/main/api/app/clients/agents/"
    click tools "https://github.com/nosportugal/librechat/tree/main/api/app/clients/tools/"
    click filestorage "https://github.com/nosportugal/librechat/tree/main/api/server/services/Files/"
    click helmmain "https://github.com/nosportugal/librechat/tree/main/helm/librechat/"
    click helmrag "https://github.com/nosportugal/librechat/tree/main/helm/librechat-rag-api/"
    click docker "https://github.com/nosportugal/librechat/blob/main/docker-compose.yml"
    click ci "https://github.com/nosportugal/librechat/tree/main/.github/workflows/"
    click dp "https://github.com/nosportugal/librechat/tree/main/packages/data-provider/"
    click ds "https://github.com/nosportugal/librechat/tree/main/packages/data-schemas/"
    click mcp "https://github.com/nosportugal/librechat/tree/main/packages/mcp/"
    click strategies "https://github.com/nosportugal/librechat/tree/main/api/strategies/"
    click config "https://github.com/nosportugal/librechat/tree/main/config/"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef backend fill:#d4edda,stroke:#333,stroke-width:1px
    classDef db fill:#fff3cd,stroke:#333,stroke-width:1px
    classDef external fill:#e2d5f7,stroke:#333,stroke-width:1px
    classDef storage fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef infra fill:#f8d7da,stroke:#333,stroke-width:1px
```
