Overview

Relevant source files

• .github/workflows/dev-build.yaml
• README.md
• cloud-deployments/helm/charts/anythingllm/README.md
• cloud-deployments/helm/charts/anythingllm/README.md.gotmpl
• cloud-deployments/helm/charts/anythingllm/values.yaml
• collector/package.json
• collector/utils/constants.js
• collector/yarn.lock
• docker/.env.example
• docker/Dockerfile
• frontend/src/pages/GeneralSettings/LLMPreference/index.jsx
• frontend/src/pages/OnboardingFlow/Steps/DataHandling/index.jsx
• frontend/src/pages/OnboardingFlow/Steps/LLMPreference/index.jsx
• package.json
• server/.env.example
• server/endpoints/embed/index.js
• server/models/embedChats.js
• server/models/systemSettings.js
• server/models/workspace.js
• server/models/workspaceChats.js
• server/package.json
• server/prisma/schema.prisma
• server/utils/chats/embed.js
• server/utils/chats/index.js
• server/utils/chats/stream.js
• server/utils/helpers/customModels.js
• server/utils/helpers/index.js
• server/utils/helpers/updateENV.js
• server/utils/middleware/embedMiddleware.js
• server/yarn.lock

Purpose and Scope

AnythingLLM is a full-stack Retrieval-Augmented Generation (RAG) application that enables users to chat with their documents using any LLM or vector database provider. This document provides a high-level overview of the system architecture, core components, and how they interact.

For detailed information on specific subsystems:

• Core architecture layers → Core Architecture
• Supported providers and integrations → Supported Integrations
• Configuration management → Configuration Management
• LLM provider integration → LLM Provider Integration
• Vector database system → Vector Database System
• Chat functionality → Chat System Architecture
• Multi-tenant workspaces → Workspace Management
• Document processing → Document Ingestion

Sources: README.md1-299 server/package.json1-113

System Characteristics

AnythingLLM is designed as a provider-agnostic RAG platform with the following key characteristics:

Characteristic	Description
Multi-Provider Support	30+ LLM providers, 10+ vector databases, 10+ embedding engines
Multi-Tenant	Workspace-based isolation with per-tenant configuration
Modular Architecture	Three-service design: frontend, server, collector
Flexible Deployment	Docker, bare metal, cloud platforms (AWS, GCP, Azure)
Runtime Configuration	Settings updated via updateENV without restart
Agent Capabilities	AIbitat framework for multi-step tool-calling workflows

Sources: README.md39-72 server/utils/helpers/updateENV.js1-1338

Repository Structure

Sources: README.md152-162 package.json1-47 server/package.json1-113 collector/package.json1-61

Three-Service Architecture

AnythingLLM operates as a monorepo with three distinct services that communicate via HTTP:

Frontend Service

• Technology: React 18 + Vite
• Port: 3000 (dev), served via reverse proxy (prod)
• Entry Point: frontend/src/main.jsx
• Purpose: User interface for workspace management, chat, and settings

Server Service

• Technology: Node.js 18+ with Express
• Port: 3001
• Entry Point: server/index.js
• Purpose: Main API server, business logic, database access, LLM/vector DB orchestration

Collector Service

• Technology: Node.js 18+ with Express + Puppeteer
• Port: 8888
• Entry Point: collector/index.js
• Purpose: Document ingestion, parsing, and processing

Sources: package.json20-28 server/package.json12-16 collector/package.json12-15 docker/Dockerfile1-223

Core Request Flow with Code Entities

Sources: server/utils/chats/stream.js1-252 server/utils/helpers/index.js84-384 server/models/workspaceChats.js1-293

Provider Architecture

AnythingLLM implements a factory pattern for all external integrations, allowing runtime provider selection:

All providers implement a common interface defined in JSDoc comments:

Sources: server/utils/helpers/index.js34-384 server/utils/helpers/updateENV.js7-830

Configuration Management System

The configuration system is the highest importance cluster (286.89 in the provided analysis) and orchestrates all system behavior:

The updateENV function at server/utils/helpers/updateENV.js1164-1220 implements a sophisticated pipeline:

1. Validation: Each field has custom validators (e.g., validOpenAIKey, supportedLLM)
2. Pre-update hooks: Test connections before persisting (e.g., validatePGVectorConnectionString)
3. Runtime update: Set process.env[key] = value
4. Post-update hooks: Trigger side effects (e.g., handleVectorStoreReset, downloadEmbeddingModelIfRequired)
5. Persistence: Write to .env file via dumpENV() and system_settings table
6. Audit logging: Record changes in event_logs table

Sources: server/utils/helpers/updateENV.js1-1338 server/models/systemSettings.js1-1164

Database Schema

AnythingLLM uses Prisma ORM with SQLite (default) or PostgreSQL:

Key tables:

• workspaces: Tenant containers with LLM/vector configuration
• workspace_chats: Chat history with optional thread/user scoping
• workspace_documents: Document-to-workspace mapping with pinned/watched flags
• documents: Document metadata and processing status
• document_vectors: Document-to-vectorId mapping for deletion
• users: Multi-user mode accounts with role-based access
• system_settings: Persisted configuration key-value pairs
• embed_configs: Public chat widget configurations

Sources: server/prisma/schema.prisma1-426 server/models/workspace.js1-1174 server/models/workspaceChats.js1-293

Technology Stack

Backend

• Runtime: Node.js 18+ (package.json17-19)
• Framework: Express 4.21+ (server/package.json54)
• ORM: Prisma 5.3.1 with SQLite/PostgreSQL support (server/package.json77-78)
• Authentication: JWT tokens via jsonwebtoken + bcryptjs hashing (server/package.json44-64)
• WebSocket: @mintplex-labs/express-ws for agent communication (server/package.json35)
• Job Scheduling: @mintplex-labs/bree for background tasks (server/package.json34)

Frontend

• Framework: React 18 (frontend dependencies)
• Build Tool: Vite 5.x (frontend build system)
• Router: React Router for client-side routing (README.md156)
• Styling: Tailwind CSS with CSS variables for theming (README.md156)
• i18n: Support for 14+ languages (README.md156)

Document Processing

• Web Scraping: Puppeteer ~21.5.2 (collector/package.json39)
• PDF Parser: pdf-parse (collector/package.json38)
• DOCX Parser: mammoth (collector/package.json30)
• OCR: tesseract.js for image text extraction (collector/package.json43)
• Audio Transcription: @xenova/transformers for local Whisper models (collector/package.json19)

AI/ML Integration

• LLM SDKs: openai, @anthropic-ai/sdk, @aws-sdk/client-bedrock-runtime, ollama, cohere-ai (server/package.json22-72)
• Vector DBs: chromadb, @pinecone-database/pinecone, @qdrant/js-client-rest, weaviate-ts-client, @lancedb/lancedb (server/package.json26-86)
• Embeddings: @xenova/transformers for native embeddings (server/package.json40)
• Agent Framework: Custom AIbitat implementation (README.md157-158)

Sources: server/package.json1-113 collector/package.json1-61 README.md152-162

Deployment Models

AnythingLLM supports multiple deployment strategies:

Deployment Type	Mechanism	Port Configuration
Docker	Multi-stage Dockerfile with ARM64/AMD64 support	3001 exposed, 3000/8888 internal
Bare Metal	Direct Node.js execution	3001 (server), 3000 (frontend), 8888 (collector)
AWS CloudFormation	IaC templates in cloud-deployments/aws/	ECS Fargate with ALB
GCP Cloud Run	IaC templates in cloud-deployments/gcp/	Container-based deployment
Kubernetes Helm	Charts in cloud-deployments/helm/	ConfigMaps for environment
Desktop Apps	Electron-based (separate repository)	Bundled services

Docker is the recommended production deployment:

• Uses Ubuntu Noble 20251013 base image (docker/Dockerfile2)
• Creates anythingllm user with configurable UID/GID (docker/Dockerfile42-46)
• Installs Node.js 18.x from NodeSource (docker/Dockerfile24-28)
• Includes Puppeteer with Chromium for web scraping (docker/Dockerfile63-70)
• Supports uvx for MCP (Model Context Protocol) compatibility (docker/Dockerfile32-36)
• Uses multi-architecture builds (ARM64 requires patched Chromium) (docker/Dockerfile8-72)

Sources: docker/Dockerfile1-223 README.md163-175 .github/workflows/dev-build.yaml1-120

Key Design Decisions

Why Three Services?

1. Isolation: Document processing (Puppeteer) isolated from API server to prevent resource contention
2. Security: Collector runs file parsers and web scrapers in separate process space
3. Scalability: Services can be scaled independently (e.g., multiple collectors for document ingestion)

Why Factory Pattern for Providers?

1. Runtime switching: Users can change LLM/vector DB without code changes
2. Extensibility: New providers added by implementing common interface
3. Workspace overrides: Per-workspace LLM selection via chatProvider/chatModel fields

Why updateENV Pipeline?

1. Validation: Prevent invalid configurations (e.g., bad connection strings)
2. Side effects: Automatically purge vector cache when embedding model changes
3. Auditability: All configuration changes logged to event_logs
4. Persistence: Dual storage (.env file + database) ensures config survives restarts

Sources: server/utils/helpers/updateENV.js1062-1094 server/utils/helpers/index.js84-384 README.md152-162