LibreChat Architecture Documentation

Version: v0.8.1-rc1 Repository: github.com/danny-avila/LibreChat License: ISC Documentation Generated: 2025-11-24

---

Table of Contents

1. System Overview
2. Sequence Diagrams
3. High-Level Architecture
4. Backend Architecture
5. Frontend Architecture
6. Shared Packages
7. Data Flow
8. Deployment Architecture
9. Security Architecture
10. Key Architectural Patterns

---

System Overview

LibreChat is a sophisticated, open-source multi-AI chat platform that provides a unified interface for multiple AI models including OpenAI, Anthropic, Google, Azure, AWS, and local models like Ollama.

---

Sequence Diagrams

1. Message Send & AI Response Flow

sequenceDiagram
    participant User
    participant ReactUI as React UI Component
    participant Recoil as Recoil State
    participant ReactQuery as React Query
    participant Express as Express API
    participant AIClient as AI Client
    participant Provider as AI Provider
    participant MongoDB
    participant MeiliSearch

    User->>ReactUI: Type message & send
    ReactUI->>Recoil: Update submission state
    Recoil->>ReactQuery: Trigger mutation
    ReactQuery->>Express: POST /api/messages
    Express->>Express: Authenticate & validate
    Express->>AIClient: Select client (OpenAI/Claude/etc)
    AIClient->>Provider: Stream chat request
    Provider-->>AIClient: Stream response chunks
    AIClient-->>Express: Forward stream
    Express->>MongoDB: Save message
    Express->>MeiliSearch: Update search index
    Express-->>ReactQuery: Stream response
    ReactQuery->>Recoil: Update cache & state
    Recoil->>ReactUI: Trigger re-render
    ReactUI-->>User: Display AI response

Loading

2. Authentication Flow

sequenceDiagram
    participant User
    participant Client as React Client
    participant Express as Express API
    participant Passport as Passport.js
    participant Strategy as Auth Strategy
    participant MongoDB
    participant Redis
    participant Provider as OAuth Provider

    User->>Client: Click login
    Client->>Express: POST /api/auth/login
    Express->>Passport: Authenticate request
    Passport->>Strategy: Execute strategy (local/oauth/ldap)

    alt OAuth Flow
        Strategy->>Provider: Redirect to OAuth
        Provider-->>Strategy: OAuth callback
        Strategy->>MongoDB: Find/create user
    else Local/LDAP
        Strategy->>MongoDB: Validate credentials
    end

    Strategy-->>Passport: User authenticated
    Passport->>Express: Generate JWT
    Express->>Redis: Create session
    Express-->>Client: Return token + user data
    Client->>Client: Store in localStorage
    Client->>Express: Future requests (Authorization header)
    Express->>Passport: Verify JWT
    Passport-->>Express: User validated

Loading

3. Application Startup Flow

sequenceDiagram
    participant Main as index.js
    participant DB as MongoDB
    participant FileStore as File Storage
    participant Config as App Config
    participant MCP as MCP Servers
    participant Express as Express App
    participant Passport as Passport
    participant Routes as API Routes

    Main->>Main: Load .env configuration
    Main->>DB: Connect to MongoDB
    DB-->>Main: Connection established
    Main->>DB: Sync indexes
    Main->>DB: Seed database
    Main->>Config: Load librechat.yaml
    Config-->>Main: App configuration
    Main->>FileStore: Initialize (S3/Firebase/Local)
    Main->>Express: Setup middleware stack
    Express->>Passport: Initialize auth strategies
    Passport-->>Express: Strategies configured
    Main->>MCP: Initialize MCP servers
    Main->>Routes: Mount API routes
    Main->>Express: Start server (port 3080)
    Express-->>Main: Server listening

Loading

4. Component Communication Flow

graph TB
    subgraph "Frontend Layer"
        ReactUI[React Components]
        RecoilState[Recoil State]
        ReactQuery[React Query]
        DataProvider[Data Provider]
    end

    subgraph "API Layer"
        Express[Express Server]
        Routes[API Routes]
        Services[Business Services]
        Middleware[Middleware Stack]
    end

    subgraph "Data Layer"
        MongoDB[(MongoDB)]
        Redis[(Redis Cache)]
        MeiliSearch[(MeiliSearch)]
        VectorDB[(PostgreSQL + pgvector)]
    end

    subgraph "External Services"
        OpenAI[OpenAI API]
        Anthropic[Anthropic API]
        Google[Google AI]
        AWS[AWS Bedrock]
        Ollama[Ollama Local]
    end

    ReactUI -->|State Updates| RecoilState
    ReactUI -->|API Calls| ReactQuery
    ReactQuery -->|HTTP Client| DataProvider
    DataProvider -->|REST API| Express
    Express -->|Route Handling| Routes
    Routes -->|Business Logic| Services
    Express -->|Validation/Auth| Middleware
    Services -->|Read/Write| MongoDB
    Services -->|Cache| Redis
    Services -->|Search| MeiliSearch
    Services -->|Vector Search| VectorDB
    Services -->|AI Requests| OpenAI
    Services -->|AI Requests| Anthropic
    Services -->|AI Requests| Google
    Services -->|AI Requests| AWS
    Services -->|AI Requests| Ollama

Loading

5. Docker Container Architecture

graph TB
    subgraph "Docker Compose Stack"
        API[LibreChat API Container<br/>Port: 3080]
        Mongo[MongoDB Container<br/>Port: 27017]
        Meili[MeiliSearch Container<br/>Port: 7700]
        PG[PostgreSQL Container<br/>Port: 5432<br/>with pgvector]
        RAG[RAG API Container<br/>Port: 8000]
    end

    subgraph "Volumes"
        DataNode[data-node/<br/>MongoDB Data]
        MeiliData[meili_data/<br/>Search Index]
        PGData[pgdata2/<br/>Vector Data]
        Uploads[uploads/<br/>User Files]
        Logs[logs/<br/>Application Logs]
    end

    API --> Mongo
    API --> Meili
    API --> RAG
    RAG --> PG
    Mongo -.-> DataNode
    Meili -.-> MeiliData
    PG -.-> PGData
    API -.-> Uploads
    API -.-> Logs

Loading

---

High-Level Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         CLIENT LAYER                            │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │   React SPA (Vite) - Port varies (dev: 3090)             │  │
│  │   • Recoil (State Management)                             │  │
│  │   • React Query (Server State)                            │  │
│  │   • React Router (Routing)                                │  │
│  │   • Tailwind CSS + Radix UI                               │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              ↕ HTTP/WebSocket
┌─────────────────────────────────────────────────────────────────┐
│                         API LAYER (Node.js)                      │
│  ┌──────────────────────────────────────────────────────────┐  │
│  │   Express.js Server - Port 3080                           │  │
│  │   • REST API Endpoints                                    │  │
│  │   • Passport.js Authentication                            │  │
│  │   • Session Management (Redis/Memory)                     │  │
│  │   • File Upload/Storage (Multer)                          │  │
│  └──────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
           ↕                 ↕                  ↕                ↕
┌──────────────────┐ ┌──────────────┐ ┌──────────────┐ ┌─────────────┐
│   MongoDB        │ │ MeiliSearch  │ │    Redis     │ │  RAG API    │
│   Port: 27017    │ │ Port: 7700   │ │ Port: 6379   │ │ Port: 8000  │
│                  │ │              │ │              │ │             │
│ • Conversations  │ │ • Full-text  │ │ • Caching    │ │ • Vector DB │
│ • Messages       │ │   search     │ │ • Sessions   │ │ • Embeddings│
│ • Users/Agents   │ │ • Indexing   │ │ • Rate limit │ │ • RAG       │
└──────────────────┘ └──────────────┘ └──────────────┘ └─────────────┘
                                                              ↕
                                                    ┌─────────────────┐
                                                    │ PostgreSQL      │
                                                    │ (pgvector)      │
                                                    │ Vector Storage  │
                                                    └─────────────────┘
           ↕
┌─────────────────────────────────────────────────────────────────┐
│                    EXTERNAL AI PROVIDERS                         │
│  OpenAI • Anthropic • Google • Azure • AWS • Ollama             │
└─────────────────────────────────────────────────────────────────┘

Technology Stack Summary

Layer	Technologies
Frontend	React 18, Vite, Recoil, React Query, Tailwind CSS, Radix UI
Backend	Node.js 20, Express.js, Passport.js, Mongoose
Database	MongoDB 8.12, PostgreSQL (pgvector)
Search	MeiliSearch 1.12
Cache	Redis (ioredis)
AI SDKs	OpenAI v5.8, Anthropic v0.52, Google AI v0.24
DevOps	Docker, Kubernetes, Playwright (testing)

---

Backend Architecture

Directory Structure

api/
├── server/
│   ├── index.js                    # Main entry point (port 3080)
│   ├── routes/                     # API Endpoints (20+ routes)
│   ├── services/                   # Business Logic (20+ services)
│   ├── middleware/                 # Express Middleware
│   └── controllers/                # Request handlers
├── app/
│   └── clients/                    # AI Provider Integrations
│       ├── BaseClient.js          # Abstract base class
│       ├── OpenAIClient.js        # OpenAI/GPT-4/o1
│       ├── AnthropicClient.js     # Claude models
│       ├── GoogleClient.js        # Gemini models
│       └── OllamaClient.js        # Local models
├── models/                         # Mongoose Database Models
│   ├── User.js                    # User accounts
│   ├── Conversation.js            # Chat sessions
│   ├── Message.js                 # Chat messages
│   ├── Agent.js                   # Custom agents
│   └── Transaction.js             # Token tracking
├── strategies/                     # Authentication Strategies
│   ├── jwtStrategy.js             # JWT auth
│   ├── localStrategy.js           # Username/password
│   ├── ldapStrategy.js            # LDAP/AD
│   └── googleStrategy.js          # Google OAuth
├── cache/                          # Caching Layer (Redis)
└── db/                             # Database Layer
    ├── connectDb.js               # MongoDB connection
    └── indexSync.js               # Index management

Startup Sequence

The backend follows a specific initialization order to ensure all dependencies are ready:

1. Environment Setup - Load .env configuration
2. Database Connection - Connect to MongoDB
3. Index Synchronization - Sync database indexes
4. Database Seeding - Populate initial data
5. Configuration Loading - Load librechat.yaml
6. File Storage Init - Initialize S3/Firebase/Local storage
7. Middleware Setup - Configure Express middleware stack
8. Authentication - Setup Passport.js strategies
9. MCP Initialization - Start Model Context Protocol servers
10. Route Mounting - Register API endpoints
11. Server Start - Listen on port 3080

API Endpoints

Route	Purpose
/api/auth	Login, logout, register, OAuth callbacks
/api/convos	CRUD for conversations
/api/messages	Message creation, updates, search
/api/users	User profile, settings, balance
/api/agents	Agent CRUD and marketplace
/api/prompts	Prompt management and sharing
/api/endpoints	AI endpoint configuration
/api/keys	API key management
/api/actions	Custom actions and tools
/api/mcp	MCP server interactions
/api/files	File upload, retrieval, deletion
/api/search	Full-text search across conversations
/api/balance	User token balance operations
/api/roles	RBAC role management
/api/share	Conversation sharing links
/api/config	App configuration retrieval

Middleware Stack

Requests flow through middleware in this order:

graph TD
    A[Request] --> B[1. noIndex<br/>SEO control]
    B --> C[2. express.json<br/>3mb limit]
    C --> D[3. mongoSanitize<br/>NoSQL injection prevention]
    D --> E[4. cors<br/>CORS headers]
    E --> F[5. cookieParser]
    F --> G[6. compression<br/>optional, gzip]
    G --> H[7. staticCache<br/>asset caching]
    H --> I[8. passport.initialize<br/>authentication]
    I --> J[9. Route Handlers]
    J --> K[10. ErrorController<br/>global error handling]
    K --> L[Response]

Loading

AI Client Architecture

All AI clients inherit from BaseClient.js and implement:

• Stream Handling - Real-time response streaming
• Token Counting - Usage tracking
• Error Handling - Provider-specific errors
• Rate Limiting - Request throttling
• Context Management - Conversation history

Supported Providers:

• OpenAI (GPT-4, GPT-4o, o1, DALL-E 3)
• Anthropic (Claude 3.5 Sonnet/Opus/Haiku)
• Google (Gemini Pro/Ultra)
• Azure OpenAI
• AWS Bedrock
• Ollama (local models)
• Custom OpenAI-compatible endpoints

Database Models

Core Mongoose schemas:

Model	Description	Key Fields
User	User accounts	email, username, password (hashed), roles
Conversation	Chat sessions	title, endpoint, model, user, agents
Message	Chat messages	text, sender, conversationId, tokens
Agent	Custom AI agents	name, description, tools, instructions
Prompt	Reusable prompts	title, prompt, category, sharing
File	File metadata	filename, type, size, userId, url
Transaction	Token usage	user, amount, type, balance
Role	RBAC roles	name, permissions
Action	Custom tools	type, metadata, auth

---

Frontend Architecture

Directory Structure

client/
├── src/
│   ├── main.jsx                   # Entry point
│   ├── App.jsx                    # Root component
│   ├── routes/                    # React Router configuration
│   ├── components/                # UI Components (50+ dirs)
│   │   ├── Chat/                 # Chat interface
│   │   ├── Messages/             # Message rendering
│   │   ├── Input/                # Message input
│   │   ├── Auth/                 # Login/register
│   │   ├── Agents/               # Agent management
│   │   ├── Nav/                  # Navigation sidebar
│   │   ├── Endpoints/            # AI endpoint selection
│   │   ├── Files/                # File browser
│   │   └── Artifacts/            # Code artifacts
│   ├── store/                     # Recoil State (15+ modules)
│   │   ├── user.ts               # User & auth state
│   │   ├── endpoints.ts          # AI endpoint state
│   │   ├── agents.ts             # Agent state
│   │   ├── submission.ts         # Message submission
│   │   └── settings.ts           # User preferences
│   ├── data-provider/             # API Client Integration
│   ├── hooks/                     # Custom React Hooks (50+)
│   ├── utils/                     # Utility Functions
│   └── locales/                   # i18n (42+ languages)
└── public/                        # Static Assets
    ├── index.html
    ├── images/
    └── assets/

Provider Hierarchy

The React app is wrapped in multiple context providers:

<ApiErrorBoundaryProvider>
  <ScreenshotProvider>
    <QueryClientProvider>        // React Query
      <RecoilRoot>               // State management
        <LiveAnnouncer>          // Accessibility
          <ThemeProvider>        // Dark/light theme
            <RadixToast.Provider>
              <ToastProvider>
                <DndProvider>    // Drag & drop
                  <RouterProvider>
                    {/* App Routes */}
                  </RouterProvider>
                </DndProvider>
              </ToastProvider>
            </RadixToast.Provider>
          </ThemeProvider>
        </LiveAnnouncer>
      </RecoilRoot>
    </QueryClientProvider>
  </ScreenshotProvider>
</ApiErrorBoundaryProvider>

State Management Pattern

LibreChat uses a dual state management approach:

┌──────────────────────────────────────────┐
│           User Interaction               │
└──────────────────┬───────────────────────┘
                   ↓
         ┌─────────────────┐
         │ React Component │
         └─────────┬───────┘
                   ↓
    ┌──────────────┴──────────────┐
    │                             │
┌───▼────────┐          ┌─────────▼────────┐
│  Recoil    │          │  React Query     │
│ (UI State) │          │ (Server State)   │
└────────────┘          └──────────────────┘
    │                             │
    │  • User preferences         │  • API calls
    │  • UI toggles               │  • Caching
    │  • Local data               │  • Mutations
    │  • Theme                    │  • Optimistic updates
    │                             │
    └──────────┬──────────────────┘
               ↓
    Component Re-render with New State

Recoil Atoms (UI State):

• User preferences and settings
• Theme selection (dark/light)
• UI toggles and modals
• Selected endpoint/model
• Active conversation

React Query (Server State):

• Conversations list
• Messages
• User data
• Agents and prompts
• File listings

Component Architecture

Key component categories:

Category	Components	Purpose
Chat	MessageList, MessageItem, ChatView	Message display and chat interface
Input	TextInput, FileUpload, ToolSelector	User input and file handling
Auth	Login, Register, OAuthButtons	Authentication flows
Agents	AgentBuilder, AgentCard, AgentMarketplace	Agent creation and management
Navigation	Sidebar, ConvoList, SearchBar	App navigation
Messages	MarkdownRenderer, CodeBlock, Artifacts	Message content rendering
Files	FileBrowser, FilePreview, FileUploader	File management
Settings	GeneralSettings, ModelSettings, Appearance	User preferences

Internationalization

LibreChat supports 42+ languages with full i18n:

• English, Spanish, French, German, Italian
• Chinese (Simplified/Traditional), Japanese, Korean
• Arabic, Hebrew, Farsi, Uyghur
• Portuguese (PT/BR), Russian, Polish, Turkish
• Vietnamese, Thai, Indonesian, Hindi
• And 25+ more languages...

Translation files: /client/src/locales/*.json

---

Shared Packages Architecture

Package Overview

packages/
├── data-provider/              # API Client Library
│   ├── Built with: TypeScript + Axios + React Query
│   └── Exports: React hooks for all API operations
│
├── data-schemas/               # Database Schemas & Types
│   ├── Built with: TypeScript + Mongoose
│   └── Exports: Schemas, types, validators
│
├── api/                        # MCP Services & Core APIs
│   ├── Built with: TypeScript + MCP SDK
│   └── Exports: MCP client, utilities
│
└── client/                     # Reusable UI Components
    ├── Built with: React + TypeScript
    └── Exports: Shared components and hooks

@librechat/data-provider

API client wrapper with React Query integration:

// Example usage
import { useGetConversationsQuery } from 'librechat-data-provider';

function ConversationList() {
  const { data, isLoading } = useGetConversationsQuery();
  // ...
}

Available Hooks:

• useGetConversationsQuery - Fetch conversations
• useCreateMessageMutation - Send message
• useGetAgentsQuery - Fetch agents
• useUpdateUserMutation - Update user profile
• 50+ more hooks for all API operations

@librechat/data-schemas

Shared TypeScript types and Mongoose schemas:

// Conversation schema
export const conversationSchema = new Schema({
  conversationId: { type: String, unique: true },
  title: { type: String, required: true },
  user: { type: Schema.Types.ObjectId, ref: 'User' },
  endpoint: { type: String, required: true },
  model: String,
  messages: [{ type: Schema.Types.ObjectId, ref: 'Message' }],
  // ...
});

@librechat/api

MCP (Model Context Protocol) services:

• MCP client implementation
• Server discovery and connection
• Tool invocation
• Resource access

---

Data Flow Architecture

Message Send Flow

Complete flow from user input to AI response:

1. User types in TextInput component
        ↓
2. Component updates Recoil submission state
        ↓
3. React Query mutation hook triggered
        ↓
4. Axios POST to /api/messages
        ↓
5. Express route handler receives request
        ↓
6. Passport.js validates JWT token
        ↓
7. Request validated and sanitized
        ↓
8. AI client selected based on endpoint
        ↓
9. Client streams request to AI provider
        ↓
10. Provider streams response chunks
        ↓
11. Response saved to MongoDB
        ↓
12. MeiliSearch index updated
        ↓
13. Stream forwarded to client
        ↓
14. React Query updates cache
        ↓
15. Recoil state updated
        ↓
16. Component re-renders with response
        ↓
17. User sees AI response

Conversation Loading Flow

1. User navigates to conversation
        ↓
2. React Router updates route
        ↓
3. useGetConversationByIdQuery hook fired
        ↓
4. Check React Query cache
        ↓
    ┌───────────────┐
    │ Cache Hit?    │
    └───┬───────┬───┘
        │       │
      YES       NO
        │       │
        │       └─→ GET /api/convos/:id
        │                    ↓
        │           Express validates & queries MongoDB
        │                    ↓
        │           Return conversation + messages
        │                    ↓
        └───────────→ Update React Query cache
                            ↓
                     Recoil state updated
                            ↓
                     Component renders messages

File Upload Flow

1. User selects file
        ↓
2. FileUpload component validates
        ↓
3. Create FormData with file
        ↓
4. POST /api/files/upload
        ↓
5. Multer middleware processes
        ↓
6. File type validation
        ↓
7. Store file (S3/Firebase/Local)
        ↓
8. Create File document in MongoDB
        ↓
9. Return file metadata
        ↓
10. Update UI with file reference
        ↓
11. Include file in message context

---

Deployment Architecture (Docker)

Docker Compose Stack

services:
  api:                      # LibreChat main application
    image: ghcr.io/danny-avila/librechat-dev:latest
    ports: ["3080:3080"]
    depends_on: [mongodb, rag_api]
    volumes:
      - ./.env:/app/.env
      - ./uploads:/app/uploads
      - ./logs:/app/logs

  mongodb:                  # Primary database
    image: mongo
    ports: ["27017:27017"]
    volumes: [./data-node:/data/db]

  meilisearch:             # Search engine
    image: getmeili/meilisearch:v1.12.3
    ports: ["7700:7700"]
    volumes: [./meili_data_v1.12:/meili_data]

  vectordb:                # Vector database
    image: pgvector/pgvector:0.8.0-pg15
    volumes: [pgdata2:/var/lib/postgresql/data]

  rag_api:                 # RAG service
    image: ghcr.io/danny-avila/librechat-rag-api-dev-lite
    ports: ["8000:8000"]
    depends_on: [vectordb]

Container Communication

┌─────────────────────────────────────────┐
│   LibreChat API Container               │
│   • Express.js server                   │
│   • Built frontend (Vite)               │
│   • Node.js runtime                     │
│   Port: 3080                            │
└───────┬─────────────────────────────────┘
        │
        ├─→ MongoDB (Conversations, Users)
        ├─→ MeiliSearch (Full-text search)
        ├─→ Redis (Caching, sessions)
        └─→ RAG API (Vector search)
                └─→ PostgreSQL+pgvector

Volume Mounts

Volume	Purpose	Persistence
data-node/	MongoDB data	Persistent
meili_data_v1.12/	Search indexes	Persistent
pgdata2/	Vector embeddings	Persistent
uploads/	User uploaded files	Persistent
logs/	Application logs	Persistent
.env	Configuration	Bind mount

Build Process

Development:

# Frontend (with hot reload)
npm run frontend:dev    # Vite dev server (port 3090)

# Backend (with nodemon)
npm run backend:dev     # Express server (port 3080)

Production:

# 1. Build shared packages
npm run build:packages

# 2. Build frontend
cd client && npm run build
# Output: client/dist/

# 3. Backend serves static files
NODE_ENV=production node api/server/index.js
# Serves client/dist/ and API on port 3080

Docker Multi-stage Build:

# Stage 1: Dependencies
FROM node:20-alpine AS deps
COPY package*.json ./
RUN npm ci

# Stage 2: Build frontend
FROM deps AS builder
COPY . .
RUN npm run build:packages
RUN cd client && npm run build

# Stage 3: Production
FROM node:20-alpine
COPY --from=builder /app/client/dist /app/client/dist
COPY --from=builder /app/api /app/api
CMD ["node", "api/server/index.js"]

---

Security Architecture

📖 For detailed security implementation, authentication methods, and GDPR compliance, see: LibreChat Security & Privacy Documentation

Security Layers

┌─────────────────────────────────────────────┐
│         1. Network Layer                    │
│  • HTTPS (production)                       │
│  • CORS configuration                       │
│  • Trusted proxy settings                   │
│  • Rate limiting                            │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         2. Application Layer                │
│  • express-mongo-sanitize                   │
│  • Input validation                         │
│  • XSS prevention                           │
│  • CSRF protection (optional)               │
│  • Content Security Policy                  │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         3. Authentication Layer             │
│  • Passport.js strategies                   │
│  • JWT token-based auth                     │
│  • OAuth 2.0 (Google, GitHub, etc.)        │
│  • LDAP/SAML (enterprise SSO)              │
│  • Two-factor authentication (2FA)         │
│  • Session management (Redis)               │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         4. Authorization Layer              │
│  • Role-based access control (RBAC)        │
│  • Permission system                        │
│  • Resource-level permissions               │
│  • Agent/prompt ownership                   │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         5. Data Layer                       │
│  • bcryptjs password hashing                │
│  • Encrypted secrets                        │
│  • File type validation                     │
│  • Image validation middleware              │
│  • Sanitized database queries               │
└─────────────────────────────────────────────┘

Authentication Strategies

Strategy	Use Case	Implementation
Local	Username/password	bcryptjs hashing, passport-local
JWT	Token-based auth	jsonwebtoken, passport-jwt
Google OAuth	Social login	passport-google-oauth20
GitHub OAuth	Developer login	passport-github2
Discord OAuth	Community login	passport-discord
LDAP	Enterprise AD	passport-ldapauth
SAML	Enterprise SSO	@node-saml/passport-saml
OpenID	Generic OAuth	passport-openidconnect

Password Security

// Password hashing (bcryptjs)
const saltRounds = 10;
const hashedPassword = await bcrypt.hash(password, saltRounds);

// Password validation
const isValid = await bcrypt.compare(inputPassword, hashedPassword);

JWT Token Flow

1. User authenticates
        ↓
2. Server generates JWT
   - Payload: { userId, email, roles }
   - Secret: process.env.JWT_SECRET
   - Expiry: 7 days (configurable)
        ↓
3. Token returned to client
        ↓
4. Client stores in localStorage
        ↓
5. Client includes in requests
   - Header: Authorization: Bearer <token>
        ↓
6. Server validates JWT
   - passport.use(jwtStrategy)
        ↓
7. Request authorized

Session Management

// Redis session store
const RedisStore = connectRedis(session);
app.use(session({
  store: new RedisStore({ client: redisClient }),
  secret: process.env.SESSION_SECRET,
  resave: false,
  saveUninitialized: false,
  cookie: {
    secure: process.env.NODE_ENV === 'production',
    httpOnly: true,
    maxAge: 7 * 24 * 60 * 60 * 1000, // 7 days
  },
}));

Input Validation & Sanitization

// MongoDB injection prevention
app.use(mongoSanitize());

// Request size limits
app.use(express.json({ limit: '3mb' }));
app.use(express.urlencoded({ extended: true, limit: '3mb' }));

// File type validation
const validateImageRequest = (req, res, next) => {
  // Validate file type, size, permissions
};

---

Key Architectural Patterns

1. Monorepo with Workspaces

{
  "workspaces": [
    "api",
    "client",
    "packages/*"
  ]
}

Benefits:

• Shared dependencies
• Centralized tooling
• Cross-package imports
• Atomic commits

2. Client-Server Separation

Frontend (React SPA)
    ↕ REST API
Backend (Express)

Benefits:

• Independent scaling
• Clear API contracts
• Technology flexibility
• Parallel development

3. Strategy Pattern (Authentication)

// Passport.js strategies
passport.use(jwtLogin());
passport.use(passportLogin());
passport.use(ldapLogin);
passport.use(googleStrategy);
// ... pluggable authentication

Benefits:

• Pluggable auth methods
• Easy to add new providers
• Consistent interface
• Testable in isolation

4. Factory Pattern (AI Clients)

class BaseClient {
  // Common interface
}

class OpenAIClient extends BaseClient {
  // OpenAI-specific implementation
}

class AnthropicClient extends BaseClient {
  // Anthropic-specific implementation
}

// Factory
function createClient(endpoint) {
  switch(endpoint) {
    case 'openAI': return new OpenAIClient();
    case 'anthropic': return new AnthropicClient();
    // ...
  }
}

Benefits:

• Uniform interface
• Easy to add providers
• Encapsulation
• Polymorphism

5. Repository Pattern (Data Access)

// Model layer (Repository)
class ConversationModel {
  static async findById(id) { /* ... */ }
  static async create(data) { /* ... */ }
  static async update(id, data) { /* ... */ }
}

// Service layer (Business logic)
class ConversationService {
  async getConversation(id) {
    return ConversationModel.findById(id);
  }
}

Benefits:

• Separation of concerns
• Testable business logic
• Swappable data sources
• Clear abstraction

6. Observer Pattern (Real-time Updates)

// Stream events
aiClient.on('data', (chunk) => {
  response.write(chunk);
});

aiClient.on('end', () => {
  response.end();
});

Benefits:

• Real-time streaming
• Decoupled components
• Event-driven architecture
• Scalable notifications

7. Composition Pattern (React Components)

<Chat>
  <MessageList>
    <Message />
    <Message />
  </MessageList>
  <MessageInput>
    <FileUpload />
    <ToolSelector />
  </MessageInput>
</Chat>

Benefits:

• Reusable components
• Flexible composition
• Clear hierarchy
• Maintainable UI

---

Performance Optimizations

Caching Strategy

┌─────────────────────────────────┐
│         Request Flow            │
└────────────┬────────────────────┘
             ↓
      ┌──────────────┐
      │ Redis Cache  │
      │ Check        │
      └──────┬───────┘
             │
        ┌────┴────┐
        │  Hit?   │
        └─┬─────┬─┘
        YES     NO
          │     │
          │     └─→ Query MongoDB
          │              ↓
          │         Cache Result
          │              ↓
          └─────────→ Return Data

Cached Data:

• User sessions
• Conversation metadata
• Model configurations
• Rate limit counters
• Search results (temporary)

React Query Caching

const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 1000 * 60 * 5,    // 5 minutes
      cacheTime: 1000 * 60 * 30,   // 30 minutes
      refetchOnWindowFocus: false,
    },
  },
});

Static Asset Optimization

// Compression
app.use(compression());

// Static file caching
app.use(staticCache(paths.dist, {
  maxAge: 86400000,  // 1 day
}));

// CDN-friendly cache headers
res.setHeader('Cache-Control', 'public, max-age=31536000');

Database Indexing

// MongoDB indexes for performance
conversationSchema.index({ user: 1, createdAt: -1 });
messageSchema.index({ conversationId: 1, createdAt: 1 });
userSchema.index({ email: 1 }, { unique: true });

---

Scalability Considerations

Horizontal Scaling

         Load Balancer
              ↓
    ┌─────────┼─────────┐
    │         │         │
 API-1     API-2     API-3
    │         │         │
    └─────────┼─────────┘
              ↓
      Shared Resources
    ┌─────────┼─────────┐
    │         │         │
 MongoDB   Redis   MeiliSearch

Considerations:

• Session sharing via Redis
• Stateless API design
• Database connection pooling
• Load balancer configuration

Resource Limits

// Connection pooling
mongoose.connect(uri, {
  maxPoolSize: 10,
  minPoolSize: 2,
});

// Request rate limiting
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000,  // 15 minutes
  max: 100,                   // 100 requests per window
});

---

Monitoring & Observability

Logging

const { logger } = require('@librechat/data-schemas');

logger.info('Connected to MongoDB');
logger.error('Failed to initialize MCP', error);
logger.warn('Rate limit exceeded', { user });

Log Locations:

• ./logs/ directory (Docker volume)
• Console output (development)
• External logging services (production)

Health Checks

app.get('/health', (req, res) => {
  res.status(200).send('OK');
});

Metrics

• Request count and latency
• Database query performance
• Cache hit/miss ratio
• AI provider response times
• Error rates by endpoint

---

Development Workflow

Local Development

# Terminal 1: Backend
npm run backend:dev

# Terminal 2: Frontend
npm run frontend:dev

# Terminal 3: Database (optional)
docker-compose up mongodb meilisearch

Testing

# Unit tests
npm run test:api        # Backend tests
npm run test:client     # Frontend tests

# E2E tests
npm run e2e            # Playwright tests
npm run e2e:headed     # With browser UI
npm run e2e:a11y       # Accessibility tests

Code Quality

# Linting
npm run lint           # ESLint check
npm run lint:fix       # Auto-fix issues

# Formatting
npm run format         # Prettier

---

Configuration Management

Environment Variables

Key .env variables:

# Server
PORT=3080
HOST=localhost

# Database
MONGO_URI=mongodb://localhost:27017/LibreChat
MEILI_HOST=http://localhost:7700

# Authentication
JWT_SECRET=your-secret-key
SESSION_SECRET=your-session-secret

# AI Providers
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

# File Storage
STORAGE_TYPE=local  # or s3, firebase

Application Configuration

librechat.yaml controls:

• AI endpoint configuration
• File storage strategies
• UI customization
• Authentication providers
• Balance/token system
• Rate limiting
• Privacy policies